This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Cortex - v2022.9

Product documentation for the Cortex automation platform, including guides, tutorials and reference documentation.

1 - What's New?

Discover what’s new in the Cortex Innovation platform.

Summary

2022.9 is the first release of the next generation of Cortex and begins our journey to improve on the previous 7.X generation starting with the following areas:

Improved Performance

This release introduces a new engine to execute automation solutions, and has shown significant performance improvements compared to 7.X, both in our own observations and customers installations. For example, one customer solution that has been migrated to 2022.9 has shown the time taken to run their tests reduce from 210 minutes to 10 minutes.

Improved Availability

This release introduces a new high availability (HA) architecture, which provides:

  • Elimination of single points of failure resulting in reduced downtime
  • The ability to perform zero downtime upgrades
  • Increased processing capacity resulting in increased throughput

Improved Usability

This release introduces:

Improved Security

This release introduces the concept of Encryptable and Encrypted text, allowing for blocks to identify and interact with sensitive data that should/must be encrypted at rest and during data transfer.

Improved Observability

This release introduces:

  • Structured logging providing a defined JSON format for logs produced by the Innovation Platform
  • Dashboards providing observability of the Innovation Platform in Production; these use structured logs as their source

Other Improvements

This release introduces a number of other improvements, such as:

For a full list of what has been introduced in this release, please see the 2022.9 Release Notes

2 - Overview

Find out what the Cortex platform is, what it can do, and how you can get started?

What is Cortex?

Low-code automation

Cortex is a low-code, automation and orchestration platform, that enables organisations to graphically capture and automate anything from simple tasks, to interactive workflows, to complex IT and business processes that span the entire organisation.

Enterprise-grade

Evolved from process and control engineering for mission-critical environments, Cortex provides enterprise-grade functionality to cover the full automation lifecycle; enabling rapid delivery of automation on-premise or in the cloud, from inception to production, without the need for software development experience.

Built for everyone

Our vision is a world where everyone can automate, and Cortex is being built for everyone, not just software developers, with the goal of removing barriers to entry and putting your people at the heart of your automation.

Comprehensive functionality

With a comprehensive set of functionality and interfaces with 3rd party systems available out-of-the-box, it’s quick and easy to get started on your automation journey.

What can it do?

Deliver quickly

Using Cortex, global organisations have been able to increase their capacity, velocity, quality, efficiency, agility and transform their business and IT operations in months.

Across multiple sectors, industries and markets

Cortex has been deployed in small, medium and large enterprises from different sectors, industries and markets, including:

For diverse sets of use cases

Cortex has been deployed for a diverse set of use cases, including:

  • Lights out monitoring and management of fixed-line telephony networks
  • Data center provisioning
  • Patching of servers
  • IT service diagnostics
  • Swivel chair operations
  • Employee onboarding and offboarding
  • Animal welfare compliance checks

Resulting in successful outcomes

Cortex has resulted in many successful outcomes, including:

  • Increased revenue
  • Increased profit
  • Redeployment of skilled employees
  • Reduction in MTTR
  • Reduction in average handling time

Accelerate your digital transformation

Wherever you are on your automation journey and whatever you are trying to achieve, small or large, simple or complex, Cortex can help accelerate a successful transformation of your operations.

How do I get started?

Getting Started Install Cortex and start your automation journey today.
Guides Learn how to use the various components that make up the Cortex platform.
Tutorials Explore all of the tutorials for the Cortex platform.
Reference Browse through the reference documentation, including details about APIs, blocks, data types, exceptions.
FAQs Find the answers to your questions.
Videos View a range of videos about the Cortex platform, automation, strategies and methodologies, as well as industry specific content.
Webinars Watch a selection of automation related webinars.
Engage With Us Let us help you to get started by participating in one of our enablement pathway programs:
1. Kickstarter - Free two/three day workshop that enables the rapid configuration of a cloud-based Cortex platform to prototype, and demonstrate automation in context.
2. Design Sprint - A two week formalised approach to automation based on our 300+ man years of knowledge and experience. Facilitated by Cortex, the Automation Design Sprint works through the required stages of automation, from vision and objectives to prototype and feedback.
3. Launch Program - A twelve week program which takes your team through the phases of mobilisation, design of automation, trial testing and sign-off to production.
4. Acceleration Program - A three, six or nine month program that delivers the framework for organisations to effectively and efficiently accelerate their team in the design, development, and delivery of automation using the Cortex platform.

3 - Getting Started

Get up and running with the Cortex Innovation platform in minutes.

3.1 - Install On-Premise

Information about installing Cortex Innovation to virtual machines or physical servers on-premise.

Cortex Innovation can be deployed on-premise on its own or added to an existing 7.2 installation.

3.1.1 - Install Innovation Only

Information about installing a Cortex Innovation platform.

Cortex Innovation can be deployed on-premise across multiple servers to provide improved scale and high availability (HA), or to a single server if scale and HA aren’t required.

3.1.1.1 - Multiple Server - With HA (Recommended)

Information about installing Cortex Innovation across multiple on-premise servers with high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions.

Multiple server installations with HA are recommended for the following scenarios:

  • Production installations that are required to scale and support HA

3.1.1.1.1 - Architecture

Information about the recommended Innovation platform architecture, including component descriptions.

Architecture

Components

Component Purpose Required/Optional Server Role
Cortex Gateway Web portal that hosts applications for creating automation solutions and managing their full life-cycle, including design, development, testing, deployment, monitoring, maintenance and ultimately end-of-life. Required Web Application Server
Cortex Studio Application hosted in Cortex Gateway that provides the graphical, low-code environment for developing, testing, versioning, publishing and managing the full life-cycle of automation solutions. Required Web Application Server
Cortex Flow Debugger Service Web application that allows flows to be debugged and executed. Used by Cortex Studio to debug flows and provide block information. Required Web Application Server
Cortex API Gateway Service Application Service that routes client requests to the correct distributed Cortex services. Required Application Server
Cortex Flow Execution Service Application Service that executes automation flows. Required Application Server
Cortex Block Packages A set of files which contain the blocks that users can use to build flows. Used by the Cortex Flow Debugger Service and the Cortex Flow Execution Service. Required Web Application Server, Application Server
Cortex Gateway Databases A set of databases created automatically by Gateway which are used for storing data related to user roles, flows, etc. Hopefully, we can remove the need for Gateway Databases in the next release. Required
(End of life)
Web Application Server
SQL Server Express or SQL Server Standard Required by Cortex Gateway for creating and storing the Gateway Databases. Hopefully, we can remove the need for SQL Server in the next release. Required
(End of life)
Web Application Server
Microsoft Service Fabric Distributed systems platform that hosts the Cortex services where automation solutions are deployed to; provides scalable, reliable and manageable enterprise-grade High Availability (HA) using clustering. Required Application Server
Microsoft Service Fabric Explorer Web portal for monitoring and managing the Service Fabric instance that automation solutions are deployed to. Required Application Server
Particular NServiceBus Messaging platform enabling scalable, reliable and flexible asynchronous messaging between distributed Cortex services. Required Application Server
Pivotal RabbitMQ Message broker used by the NServiceBus messaging platform to transport messages asynchronously between distributed Cortex services using publish/subscribe mechanism. Required Application Server
Erlang OTP Erlang run-time required by the RabbitMQ message broker. Required Application Server
gobetween L4 load balancer and reverse proxy used to load balance requests between clustered instances of Cortex services. Required Load Balancer
NSSM Windows Service Manager that hosts the gobetween load balancer application as a Windows Service. Required Load Balancer

The following architecture requires 5 servers:

  • 1x Web Application Server which contains Gateway, Flow Debugger Service and Databases
  • 1x Load Balancer Server
  • 3x Application Servers

5 Server Architecture Diagram

Next Steps?

  1. Prerequisites

3.1.1.1.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for each server role (as described in Architecture) are laid out in this guide. These must be considered before undertaking installation.

Hardware Requirements

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
Load Balancer 11 4+ Recommended
Minimum
8+ Recommended
Minimum
50+ Recommended
30 Minimum
5+ free on installation drive
Application Server Bronze availability2
Silver availability
Gold availability
Platinum availability
4+ Recommended
Minimum
16+ Recommended
Minimum
75+ Recommended
60 Minimum
40+ free on %ProgramData% drive
Web Application Server 1 4+ Recommended
Minimum
8+ Recommended
Minimum
75+ Recommended
50 Minimum
30+ free on installation drive

Software Requirements

Server Role Windows Server3 SQL Server4 .Net PowerShell5 IIS6 Other Software
Load Balancer 2019 (x64) Recommended
2016 (x64)
Framework 4.7.1 5.1
Application Server 2019 (x64) Recommended
2016 (x64)
Framework 4.7.1 5.1
Web Application Server 2019 (x64) Recommended
2016 (x64)
2019
2016
2016 Express
Framework 4.7.1 5.1 10.0.177637
10.0.143938
URL Rewrite Module 2.1
Microsoft Web Deploy 3.0 or later
Visual C++ Redistributable 2013 (x64)

Domain Requirements

All servers must be on the same domain and cannot be domain controllers.

DNS Requirements

The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for all of your servers (Web, Application and Load Balancer).

Licensing Requirements

A valid Cortex licence file and Cortex Innovation feature identifier must be procured from Cortex. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the Web Application server and it should contain fingerprints for the Web Application Server and each Application Server.

To get a licence file and feature identifier take the following steps:

  1. Copy the following template to a text file:

    Web Application Server
    MachineID: 
    Fingerprint: 
    
    Application Server 1
    MachineID: 
    Fingerprint: 
    
    Application Server 2
    MachineID: 
    Fingerprint: 
    
    Application Server 3
    MachineID: 
    Fingerprint: 
    
    Please also include a suitable Cortex Innovation feature identifier.
    
  2. Extract Cortex Innovation 2022.9 - Licence Fingerprint Generator.zip.

  3. From that folder, copy Cortex.Licensing.FingerprintGeneration.exe to the Web Application server.

  4. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

    MachineID: WEBAPP-SERVER
    Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
    
  5. Copy the output (machine identifier and fingerprint) to the Web Application Server section of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server.

  6. For each Application Server take the following steps:

    1. Copy Cortex.Licensing.FingerprintGeneration.exe to the Application server.

    2. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

      MachineID: APP-SERVER1
      Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
      
    3. Copy the output (machine identifier and fingerprint) to one of the Application Server sections of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server.

  7. Request a licence and feature identifier by raising a case in the Cortex Service Portal, including the contents of the text file containing all of the fingerprint and machine information in the body of the case.

  8. When the licence and feature identifier have arrived, copy the file Cortex.lic to %ProgramData%\Cortex\Licences on the Web Application Server, creating the Cortex and Licences folders if they don’t exist. Save the feature identifier for use when Installing Gateway.

Web Browser Requirements

Gateway supports the latest versions of the following browsers:

  • Chrome
  • Edge
  • Firefox

Additional Load Balancer Server Requirements

Filesystem Requirements

If using the included gobetween load balancer, Network Discovery and File Sharing must be enabled on the Load Balancer Server:

  1. Open File Explorer.
  2. Click Network on the left.
  3. A banner similar to the following will appear if Network Discovery and File Sharing is turned off:

    Network and File Discovery Disabled

  4. Click the banner.
  5. Click Turn on network discovery and file sharing:

    Enable Network and File Discovery

Alternative Load Balancer Requirements

Innovation has a gobetween load balancer included that isn’t highly available; It is possible to use an alternative. The requirements for installing an alternative load balancer are as follows:

  • Must support a round robin (or similar) method of load balancing to specified ports on 3 nodes.
  • Must be able to health check each node by running a predefined batch script (ApiGatewayTypeHealthcheck.bat, which resides in the gobetween folder of the Cortex Innovation 2022.9 - App Server Install Scripts) that returns 1 for healthy and 0 for unhealthy.
  • Must be able to access each of the Application Servers via HTTPS.
  • Ideally it should be highly available to avoid a single point of failure in the system.

Additional Application Server Requirements

Filesystem Requirements

All Application Servers must use an NTFS filesystem.

Network Discovery and File Sharing should be enabled on each Application Server:

  1. Open File Explorer.
  2. Click Network on the left.
  3. A banner similar to the following will appear if Network Discovery and File Sharing is turned off:

    Network and File Discovery Disabled

  4. Click the banner.
  5. Click Turn on network discovery and file sharing:

    Enable Network and File Discovery

Service Requirements

The following Windows Services must be running on all Application Servers:

  • Remote Registry
  • Windows Event Log
  • Performance Logs & Alerts

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on all Application Servers and Load Balancer Server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the HA platform that Cortex Innovation is built upon.

Antivirus Exclusions

It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on each Application Server to reduce antivirus processing on Service Fabric artefacts:

Folder Exclusions:

  • %ProgramFiles%\Microsoft Service Fabric
  • %ProgramData%\SF
  • %ProgramData%\SF\Logs

Process Exclusions:

  • Fabric.exe
  • FabricHost.exe
  • FabricInstallerService.exe
  • FabricSetup.exe
  • FabricDeployer.exe
  • ImageBuilder.exe
  • FabricGateway.exe
  • FabricDCA.exe
  • FabricFAS.exe
  • FabricUOS.exe
  • FabricRM.exe
  • FileStoreService.exe

A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually.

If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist.

Port Requirements

Cortex Innovation and Microsoft Service Fabric require a range of firewall ports to be opened between the servers and specific services.

If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in Port Requirements to open the correct ports.

The Cortex.Innovation.Test.PortUsage.ps1 script is provided during installation to test the ports on each Application Server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible.

Certificate Requirements

An X.509 SSL wildcard certificate should be used to:

  • Secure communication between the load balancer and the nodes on the Application Servers.
  • Secure communication between the Application Services.
  • Allow Application Services to identify themselves to clients such as Gateway.
  • Prevent unauthorised nodes from joining the HA cluster.
  • Connect to Service Fabric Explorer from each of the Application Servers.

The certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in a wildcard format, pertaining to the domain of the Application Servers (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.
  • Key Usage extension must have a value of Digital Signature, Key Encipherment (a0).
  • Enhanced Key Usage must include Server Authentication and Client Authentication.

This file should be placed in a known location on the Application Server where the installation scripts will be run. This location will be required when running the installation script.

If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject field can also be the FQDN of the load balancer (e.g. CN=machine-name.domain.com).

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the Application Servers, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the Application Servers.

Additional Web Application Server Requirements

Security Requirements

Installation User

Domain users must be available to run the Application Pools for Gateway and Flow Debugger Service. These users must be given Log on as a service and Log on as a batch job permissions otherwise the Application Pools will not be able to run. Information about how to do this will be given during installation.

For Flow Debugger Service, the NETWORK SERVICE user can also be used.

Domain Requirements

For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported.

Supported versions of Active Directory are listed below:

Version Verified? Supported From Supported Until
Windows Server 2003 Cortex v2022.9 To be evaluated
Windows Server 2003 R2 Cortex v2022.9 To be evaluated
Windows Server 2008 Cortex v2022.9 To be evaluated
Windows Server 2008 R2 Cortex v2022.9 To be evaluated
Windows Server 2012 Cortex v2022.9 To be evaluated
Windows Server 2012 R2 Cortex v2022.9 To be evaluated
Windows Server 2016 Cortex v2022.9 To be evaluated
Windows Server 2019 Cortex v2022.9 To be evaluated
Windows Server 2022 Cortex v2022.9 To be evaluated

Certificate Requirements

Both Gateway and the Flow Debugger Service require an X.509 SSL certificate to be installed on the Web Application Server. The certificate must have the following properties:

  • Enhanced Key Usage: Server Authentication and Client Authentication
  • Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1

If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error.

Wildcard certificates and self-signed certificates can also be used. However, self-signed certificates are not recommended for production instances. Details on how to create a self-signed certificate can be found at Create Self-Signed Certificates.

The certificate may be the same one used for the Application Server installation.

More information about importing the certificate is given during installation.

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the Web Application Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the Web Application Server.

Next Steps?

  1. Install Application Servers and Load Balancer

  1. A software-based load balancer called gobetween is provided with the platform. This must be installed on its own server as it doesn’t support routing traffic to itself. It also doesn’t currently support HA, but it may be possible to use multiple gobetween load balancers with Anycast network addressing and routing to provide high availability, as described in https://en.wikipedia.org/wiki/Anycast; however, this has not been verified yet. It is possible to use an alternative load balancer to the one provided. ↩︎

  2. Application Servers support HA via clustering. A cluster must consist of a minimum of 3 nodes, and the number of nodes must be an odd number to ensure a quorum. Currently only the Bronze availability (3 nodes) is supported. Silver, Gold and Platinum support will be added in future. ↩︎

  3. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

  4. SQL Server Express, Standard and Enterprise are supported. Other databases are not supported. Note that Transparent Data Encryption is not supported on SQL Server Express. ↩︎

  5. PowerShell 5.1 ships with Windows Server 2016 and 2019. ↩︎

  6. IIS is supported; other web servers, including IIS Express are not supported. ↩︎

  7. Ships as a windows role within Windows Server 2019. ↩︎

  8. Ships as a windows role within Windows Server 2016. ↩︎

3.1.1.1.3 - Install Application Servers and Load Balancer

Information about installing the Application Servers and Load Balancer Server.

Install Application Servers and Load Balancer

This guide describes how to install the Application Servers and Load Balancer Server. Please ensure that the Prerequisites for installing Innovation have been read before starting this installation.

Make Installation Artefacts Available

  1. Choose one of the Application Servers to be used for installation, and copy the following artefacts to a folder on it (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - App Services.zip
    • Cortex Innovation 2022.9 - App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - App Server Install Scripts.zip file to a folder with the same name.

Install Microsoft .NET Framework 4.7.1

Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.1 to be installed on each Application Server.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

These are non-compulsory security measures, recommended to be applied to Application Servers and the Load Balancer Server, in order to prevent potential attacks that exploit known industry security vulnerabilities.

Applying these measures may impact other applications running on your servers. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes.

A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at SSL Best Practices.

The settings can be applied by running a script. Be aware that each server will be restarted when the script is run. Apply the settings by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the LoadBalancerServer value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the LoadBalancerServer parameter if using an alternative load balancer):

    .\Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server"
    
  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

    If -Override 0 has been specified no further steps need to be taken and you can move on to the next section when the servers have restarted.

  5. To use all the recommended settings click Apply all to the each Apply Cortex recommended security best practices prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying. This will need to be done for each server.

  6. Restart each machine when the script asks. The current machine will be restarted last, the PowerShell script will close at this time.

Add Antivirus Exclusions

  1. If Windows Defender is not running on the Application Servers, ensure that the Antivirus Exclusions have been added to the running antivirus software on each of the Application Servers and continue to the next section, otherwise follow these steps:
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers:

      .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK.

    5. A message will indicate that the script has completed successfully.

Check Port Usage

  1. To check all necessary ports are free, follow these steps.
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Test.PortUsage.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers:

      .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK.

    5. If all ports are free, the script will report the following for each Application Server:

      All ports required by Cortex Innovation are free

      If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the Cortex.Innovation.Install.Config.json configuration file, in the Cortex Innovation 2022.9 - App Server Install Scripts folder, to use different ports. This will be used later during installation.

      The Cortex.Innovation.Test.PortUsage.ps1 script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, locate the Cortex.Innovation.Install.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -LoadBalancerServerIPv4Address "192.168.1.4" `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -ClientCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ClientCertificatePwd "myPassword" `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -LoadBalancerServerIPv4Address "192.168.1.4" `
        -UseSelfSignedCertificates `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -ClientCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ClientCertificatePwd "myPassword" `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -UseSelfSignedCertificates `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    Name Description
    AppServicesPath Configure this value with the location of the Application Services zip file on the Application Server used for installation.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the Application Server used for installation.
    ApiGatewayBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when installing Gateway.
    ApiGatewayBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when installing Gateway.
    CustomerName A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer.
    ApplicationServerIPv4Addresses The IPv4 addresses of the Application Servers. The first of these must be the Application Server used for installation.
    LoadBalancerServerIPv4Address The IPv4 address of the Load Balancer Server. This is only needed if using the built-in load balancer.
    ServerCertificatePath The local path of a .PFX certificate file on the first Application Server in the ApplicationServerIPv4Addresses list. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended). The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the Application Services.
    • Allowing Application Services to identify themselves to clients such as Gateway.
    • Preventing unauthorised nodes from joining the HA cluster.
    • Connecting to Service Fabric Explorer from each of the Application Servers.
    ServerCertificatePwd The password for the .PFX certificate file specified in ServerCertificatePath.

    This is only needed if installing with CA Certificates (Recommended).
    ClientCertificatePath The local path of a .PFX certificate file on the first Application Server in the ApplicationServerIPv4Addresses list. This can be the same certificate as the ServerCertificatePath. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the load balancer and the nodes on the Application Servers.
    ClientCertificatePwd The password for the .PFX certificate file specified in ClientCertificatePath.

    This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer.
    UseSelfSignedCertificates Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    SkipLoadBalancer Installs Application Services and required infrastructure without installing a load balancer. Use when using an alternative load balancer or no load balancer.
    Credential The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.

    The ApiGatewayBasicAuthUserName and ApiGatewayBasicAuthPwd will be needed later, when installing Gateway.

  3. Save and close Cortex.Innovation.Install.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1 -WhatIf
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -WhatIf -AcceptEULA
    
  5. Run the PowerShell command to test the installation script.

  6. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

  7. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ.

  8. Wait for the command to finish. It will display the output of the installation command without making any changes to the system, to ensure things like communication between the servers are working.

  9. Check that there have been no errors in the script; these would appear in red in the console.

    If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them.

    If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

    If this does not work, please contact Cortex Service Portal for further assistance. The WhatIf script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with -WhatIf (e.g. Cortex.Innovation.Install.Config-WhatIf.json). This file can be provided when obtaining support.

Run Installation Script

  1. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1
    
  2. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  3. Run the PowerShell command to install HA Services and the required infrastructure.

  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

  5. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from Cortex Service Portal. Press OK.

  6. Wait for the script to finish running. This should take approximately 10 minutes.

  7. Check that there have been no errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation.

    In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command:

    .\Cortex.Innovation.Uninstall.ps1
    

    If the errors do not give any instructions on how to rectify, see Troubleshooting During Installation for further information; if this does not help then please contact Cortex Service Portal for assistance.

Check Application Services

  1. Log on to one of the Application Servers.

  2. Import the client certificate, used in the ClientCertificatePath parameter of the Configure Installation Script section, to your Current User certificate store. This can be achieved by double clicking on the client certificate .PFX file and following the wizard.

    If using self-signed certificates, the certificate can be retrieved by using the Manage Computer Certificates tool in Windows to export the CortexServerCertificate from the Personal store and then importing it to the Current User store by double-clicking on it and following the wizard.

  3. Open a web browser.

  4. Navigate to https://app-server.domain.com:9080/Explorer, where app-server.domain.com is the fully qualified domain name of any Application Server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    The screen should resemble that in the following figure:

    Healthy Service Fabric Explorer Cluster

    The status circles should be entirely green - this indicates that all nodes, services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system.

    After expanding the application, clicking on any of the services should display a green circle and Status = Active:

    Healthy Service Fabric Explorer Service

    After expanding either of the services, clicking on any of the instances/partitions should display a green circle and Status = Ready:

    Healthy Service Fabric Explorer Instance

    Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and Status = Up:

    Healthy Service Fabric Explorer Node

    If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section.

    If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong.

    If no useful message can be seen here, the service log files may contain more information. These can be found on each Application Server at:

    • %ProgramData%/Cortex/Cortex API Gateway Service
    • %ProgramData%/Cortex/Cortex Flow Execution Service

    If no solution can be found, please contact Cortex Service Portal for further assistance.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Install Web Application Server

3.1.1.1.4 - Install the Web Application Server

Information about installing the Web Application Server.

Install the Web Application Server

This guide describes how to install the Web Application Server. Please ensure that Install Application Servers and Load Balancer has been completed before starting this installation.

Make Installation Artefacts Available

  1. We recommend that the Flow Debugger Service and Gateway are installed on the same Web Application Server. Copy the following artefacts to a folder on the machine (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - Gateway.zip
    • Cortex Innovation 2022.9 - Flow Debugger Service.zip
    • Cortex Innovation 2022.9 - Web App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - Web App Server Install Scripts.zip zip file to a folder with the same name.

Install Prerequisites

Licensing

Ensure that a valid Cortex licence file named Cortex.lic exists on the Web Application server, in the location %ProgramData%\Cortex\Licences. If it does not, follow the instructions located at Licensing Requirements.

Install SQL Server or SQL Express

  1. Use one of the following installation guides to install SQL Server or SQL Server Express:

Install Microsoft .NET Framework 4.7.1

Gateway requires a minimum of Microsoft .NET Framework 4.7.1.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

Install Microsoft Web Deploy

  1. Check if Web Deploy is already installed by going to Control PanelProgramsPrograms and Features; if Web Deploy is already installed, it will be listed as Microsoft Web Deploy.
  2. If it is not installed, download Microsoft Web Deploy version 3.0 or later (WebDeploy_amd64_en-US.exe) to the server.
  3. Double-click the downloaded file to start the installation.
  4. Follow the installation wizard to install Web Deploy; on the Choose Setup Type page select Typical.

Install Visual C++ Redistributable

  1. Check if Visual C++ 2013 Redistributable (x64) is already installed by going to Control PanelProgramsPrograms and Features; if Visual C++ Redistributable is already installed, it will be listed as Microsoft Visual C++ 2013 Redistributable (x64).
  2. If it is not installed, download Visual C++ Redistributable 2013 (x64).
  3. Double-click the downloaded file to start the installation.
  4. Follow the installation wizard to install the Visual C++ Redistributable.

Install Certificate

Both Gateway and the Flow Debugger Service require an X.509 SSL certificate to be installed on the Web Application Server. The certificate must have the following properties:

  • Enhanced Key Usage: Server Authentication and Client Authentication
  • Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1

If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error.

Wildcard certificates and self-signed certificates can also be used. However, self-signed certificates are not recommended for production instances. Details on how to create a self-signed certificate can be found at Create Self-Signed Certificates.

You can import the certificate by right clicking the certificate file, selecting Install Certificate and following the wizard. When prompted, ensure you import it into the Local Machine store and not Current User.

To verify the certificate is imported:

  1. Click the Windows button (Start)
  2. Type certlm.msc and press Enter to open the Certificate Manager dialog
  3. Expand Personal and select Certificates
  4. You should see your certificate in this store

IIS Role Setup and Configuration

Install Internet Information Services (IIS)

Install the required features by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.WindowsFeatures.ps1 script using the following command, this may take a few minutes:

    .\Cortex.Innovation.Install.WindowsFeatures.ps1
    
  4. Check the output is as follows:

    Web-WebSockets is installed
    Web-Asp-Net45 is installed
    Web-Net-Ext45 is installed
    Web-ISAPI-Ext is installed
    Web-ISAPI-Filter is installed
    Net-Framework-45-Core is installed
    Net-Framework-45-ASPNET is installed
    Web-Default-Doc is installed
    Web-Dir-Browsing is installed
    Web-Http-Errors is installed
    Web-Static-Content is installed
    Web-Http-Logging is installed
    Web-Http-Redirect is installed
    Web-Request-Monitor is installed
    Web-Stat-Compression is installed
    Web-Dyn-Compression is installed
    Web-Filtering is installed
    Web-Windows-Auth is installed
    Web-Mgmt-Console is installed
    Web-Mgmt-Service is installed
    

Register and Allow .NET CLR v4.0.30319 with IIS

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Run the following command:

    Dism /online /enable-feature /featurename:IIS-ASPNET45 /all
    
  3. Once PowerShell confirms that it has finished installing .NET CLR v4.0.30319, close the PowerShell window.

Install URL Rewrite Module

The URL Rewrite IIS Manager module is required to enable web applications on your server to rewrite URLs. This is needed to allow HTTP URLs to redirect to the equivalent HTTPS ones.

To install the URL Rewrite module take the following steps:

  1. In the left-hand pane of Internet Information Service (IIS) Manager, select the server node.
  2. Ensure that there is an icon with the title URL Rewrite under the IIS feature section:

    Url Rewrite Module Icon

  3. If there is an icon, URL Rewrite module is installed and no further steps are required.
  4. If there is no icon, the module is not installed and the following steps must be taken:
    1. Download the URL Rewrite module installer.
    2. Double-click on the installer file to run it.
    3. Follow the wizard to complete the installation.
    4. After successfully installing, close and reopen IIS Manager. The URL Rewrite icon should now be visible.

These are non-compulsory security measures, recommended to be applied to Web Application Servers, in order to prevent potential attacks that exploit known industry security vulnerabilities.

Applying these measures may impact other applications running on your server. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes.

A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at SSL Best Practices.

Apply the settings by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.SSLBestPractices.ps1 script using the following command:

    .\Cortex.Innovation.Install.SSLBestPractices.ps1
    

    If -Override 0 has been specified no further steps need to be taken and you can move on to the next section when the server has restarted.

  4. To use all the recommended settings click Apply all to the first prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying.

  5. Restart the machine when the script asks.

Add HTTPS Firewall Rule

If any firewall is running on the Web Application Server, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443). See Configure Firewalls for information about adding rules to Windows Firewall.

Create Web Site

Gateway and Flow Debugger Service can either be installed to an existing web site or a newly created web site. If you are installing into an existing web site skip to Configure Web Site.

The steps to create a new web site are:

  1. In Windows File Explorer, navigate to the default IIS folder (usually %SystemDrive%\inetpub\wwwroot, e.g. C:\inetpub\wwwroot).
  2. Ensure there is a folder called Cortex; if not create it.
  3. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  4. Right-click the Sites node under the server and select Add Website….
  5. Set the Site name to Cortex.
  6. Set the Physical path to the folder created above (e.g. C:\inetpub\wwwroot\Cortex), by clicking on the ellipses , selecting the appropriate directory and clicking OK.
  7. Click OK. If an existing site is already using the specified port, a warning will be displayed. Either click No and change the Port in the Add Website dialog, or click Yes and stop the other website.

Configure Web Site

The web site which the Gateway and Flow Debugger Service are installed under requires additional configuration.

Configure HTTPS

Both the Gateway and Flow Debugger Service should be configured to use HTTPS:

  1. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  2. Expand the Sites node under the server.
  3. Right-click the web site where Gateway will be installed and select Edit Bindings….
  4. Click Add…
  5. Set Type to https.
  6. Set the appropriate Port number (typically 443). The Host name box can be left blank.
  7. Select the SSL certificate that was installed in the Install Certificate section.
  8. Click OK. If an existing site is already using the specified SSL port, a warning will be displayed. Either click No and change the Port in the Add Site Binding dialog, or click Yes and stop the other website.
  9. It is recommended to remove the http site binding.

Install Flow Debugger Service

Get Application Pool User

A domain user account is required for the Flow Debugger Service web application pool and must be created prior to performing the installation. In line with best practices, this account should not be used for any purposes other than those specified for the Flow Debugger Service. Alternatively, the NETWORK SERVICE user may also be used.

This user must currently have access to the default NuGet directory, in order to load block packages correctly. To add permissions for the user take the following steps:

  1. Navigate to %SystemRoot%\System32\config\systemprofile\AppData\Roaming\ and create a new folder named NuGet if one does not exist.
  2. Right-click on the NuGet folder and click Properties.
  3. In the dialog, click the Security tab.
  4. Click the Edit... button.
  5. Click the Add... button.
  6. Enter the username of the application pool user and click OK.
  7. In the Permissions section at the bottom, check Full control
  8. Click OK.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.FlowDebuggerService.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -UseSelfSignedCertificates `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    Name Description
    FlowDebuggerServicePath Configure this value with the location of the Flow Debugger Service zip file on the Web Application Server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the Web Application Server.
    FlowDebuggerBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when installing Gateway.
    FlowDebuggerBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when installing Gateway.
    UseSelfSignedCertificates Enables Flow Debugger Service to communicate with Gateway using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    Credential The credentials of the user that will be used to run the Debugger application pool in IIS.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.FlowDebuggerService.ps1.

Run Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.FlowDebuggerService.ps1
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  5. Run the PowerShell command to install the Flow Debugger Service.

  6. A credentials prompt will appear. Enter the credentials of the user that should run the Debugger application pool in IIS. If using the NETWORK SERVICE user, enter any user as the username and leave the password blank; the NETWORK SERVICE user will need to be selected in the final step.

  7. Wait for the script to finish running. This should take approximately 2 minutes.

  8. An error may have appeared saying:

    The Windows Process Activation Service service is not started.
    

    This can be ignored.

  9. Check that there have been no other errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation.

    If the errors do not give any instructions on how to rectify, please contact Cortex Service Portal for further assistance.

  10. If using NETWORK SERVICE for the application pool user:

    1. Open Internet Information Services (IIS) Manager.
    2. On the left, expand the server node.
    3. Click Application Pools.
    4. Right-click on the Debugger application pool and select Advanced Settings....
    5. In the Advanced Settings dialog, click on Identity and then click the ellipses (...).
    6. In the Application Pool Identity dialog, select Built-in account, then select NetworkService from the drop-down, then click OK.
    7. Right-click on the Debugger application pool and click Recycle....

Install Gateway

Get Application Pool User

A domain user account is required for the Gateway web application pool and must be created prior to performing the installation below.

This user account is required to enable Gateway to access the Cortex database, with the following roles:

  • dbcreator
  • public

To add roles to database users take the following steps:

  1. Open SQL Server Management Studio on the Web Application Server and log in.

  2. Expand the server node, then Security then Logins.

  3. If the user that will run the Gateway application pool is not in the list of logins, take the following steps, otherwise skip to step 4:

    1. Right-click the Logins node and click New Login....
    2. Enter the application pool user in the Login name box.
    3. On the left pane, click Server Roles.
    4. Check public and dbcreator
    5. Click OK.
  4. If the user that will run the Gateway application pool is in the list of logins, take the following steps:

    1. Right-click on the application pool user.
    2. Click Properties.
    3. On the left pane, click Server Roles.
    4. Check public and dbcreator.
    5. Click OK.

In line with best practices, this account should not be given administrator rights, nor should it be used for any purposes other than those specified for Gateway.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Create Gateway Application Pool

  1. Open Internet Information Services (IIS) Manager.
  2. Select and right-click the Application Pools node under the server and select Add Application Pool…
  3. Set Name to Cortex Gateway.
  4. Ensure that the .NET CLR version is set to .NET CLR Version v4.0.30319 (This may be configured by default).
  5. Ensure that the Managed pipeline mode is set to Integrated (This may be configured by default).
  6. Click OK
  7. Right click on the created application pool and select Advanced Settings…
  8. Click the ... next to Identity (under Process Model) to open a dialog, then select Custom Account and Set....
  9. Enter the username and password for the user identified in Get Application Pool User.
  10. Click OK to close the Set Credentials dialog.
  11. Click OK to close the Application Pool Identity dialog.
  12. Click OK to close the Advanced Settings dialog.

Create New Web Application

  1. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  2. Right-click on the site the application should be installed under and select Add Application…
  3. Set the Alias to gateway. This must be lowercase.
  4. Click Select… and from the Application pool dropdown select the Cortex Gateway application pool and click OK.
  5. Set the Physical path to C:\inetpub\wwwroot\Cortex\Gateway by clicking on the ellipses and selecting the appropriate directory. Create the C:\inetpub\wwwroot\Cortex\Gateway directory if it does not already exist.
  6. Click OK.

Configure IIS Site Redirect to the Specified Web Application (Optional)

If the site hosting the Gateway web application is a newly created Cortex site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the gateway web application URL, e.g. https://FullyQualifiedDomainName to https://FullyQualifiedDomainName/gateway.

  1. Open Internet Information Services (IIS) Manager.
  2. Select the site hosting the gateway web application and from IIS settings double-click the HTTP Redirect icon.
  3. Click the check box Redirect requests to this destination.
  4. Enter https://FullyQualifiedDomainName/gateway, replacing FullyQualifiedDomainName with the FQDN of the server.
  5. In the Redirect Behaviour section, click Only redirect requests to content in this directory (not subdirectories).
  6. In Actions click the Apply button.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.Gateway.ps1 script and open it with a text editor.

  2. Configure the script according to the details given below:

    .\Cortex.Install.Gateway.ps1 `
    -GatewayPackagePath "C:\Install\Cortex Innovation 2022.9 - Gateway.zip" `
    -GatewayApplicationIISPath "Cortex\gateway" `
    -ModelDBContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb;Integrated Security=True;MultipleActiveResultSets=True" `
    -AuthContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb.Auth;Integrated Security=True;MultipleActiveResultSets=True" `
    -SignalRContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb.SignalR;Integrated Security=True;MultipleActiveResultSets=True" `
    -FeatureFlags "InnovationId" `
    -ServiceFabricApiGatewayEndpoint "https://server.domain.com/" `
    -ServiceFabricUsingSelfSignedCertificates $false `
    -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" `
    -ServiceFabricApiGatewayBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerEndpoint "https://server.domain.com/debugger/api/" `
    -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" `
    -DotNetFlowDebuggerBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerUsingSelfSignedCertificates $false `
    -Test:$Test `
    -AcceptEULA:$AcceptEula `
    *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt"
    
    Name Description
    GatewayPackagePath Configure this value with the location of the Cortex Innovation 2022.9 - Gateway.zip file on the installation server.
    GatewayApplicationIISPath Change to the correct Site Name/Application if either was modified from the defaults (Cortex/gateway) when creating the website or application.
    ModelDBContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost or, if it was installed on another machine, change it to the machine name.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance or, if SQL Server was installed on a different machine, change it to {machineName}\{instanceName} replacing {machineName} with the machine name and {instanceName} with the name of the instance.

    This will set the ModelDBContextConnectionString value in the Gateway web.config.
    AuthContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost or, if it was installed on another machine, change it to the machine name.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance or, if SQL Server was installed on a different machine, change it to {machineName}\{instanceName} replacing {machineName} with the machine name and {instanceName} with the name of the instance.

    This will set the AuthContextConnectionString value in the Gateway web.config.
    SignalRContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost or, if it was installed on another machine, change it to the machine name.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance or, if SQL Server was installed on a different machine, change it to {machineName}\{instanceName} replacing {machineName} with the machine name and {instanceName} with the name of the instance.

    This will set the SignalRContextConnectionString value in the Gateway web.config.
    FeatureFlags Replace InnovationId with the Cortex Innovation feature identifier, which should have been provided by Cortex when fulfilling the Licensing Requirements, if it wasn’t it should be requested using Cortex Service Portal.

    This will set the FeatureFlags value in the Gateway web.config.
    ServiceFabricApiGatewayEndpoint Replace server.domain.com with the fully qualified domain name of the Load Balancer Server. The port should be specified if it is not the default HTTPS port (443), and there must be a trailing slash, e.g. https://server.domain.com/ or https://server.domain.com:8722/.

    This will set the ServiceFabricApiGatewayEndpoint value in the Gateway web.config.
    ServiceFabricUsingSelfSignedCertificates Configure the value as $false if you used valid CA certificates when installing the Application Servers, $true if you used self-signed certificates.

    This will set the ServiceFabricUsingSelfSignedCertificates value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthUsername This must be changed if you used a non-default ApiGatewayBasicAuthUserName when installing the Application Servers; if so, this value must be configured to the one used.

    This will set the ServiceFabricApiGatewayBasicAuthUsername value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthPassword This must be changed if you used a non-default ApiGatewayBasicAuthPassword when installing the Application Servers; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will set the ServiceFabricApiGatewayBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerEndpoint Replace server.domain.com with the fully qualified domain name of the Web Application Server.

    This will set the DotNetFlowDebuggerEndpoint value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthUsername This must be changed if you used a non-default FlowDebuggerBasicAuthUserName when installing the Flow Debugger Service; if so, this value must be configured to the one used.

    This will set the DotNetFlowDebuggerBasicAuthUsername value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthPassword This must be changed if you used a non-default FlowDebuggerBasicAuthPassword when installing the Flow Debugger Service; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will set the DotNetFlowDebuggerBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerUsingSelfSignedCertificates Configure the value as $false if you are using valid CA certificates to secure the site containing Gateway and Flow Debugger Service, $true if using self-signed certificates.

    This will set the DotNetFlowDebuggerUsingSelfSignedCertificates value in the Gateway web.config.
    Test This does not need to be changed, it will be set at a later stage.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.Gateway.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1 -Test
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -Test -AcceptEULA
    
  5. Run the PowerShell command to test the configuration. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

Run Installation Script

  1. Ensure the Gateway application pool is stopped:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Stop.
  2. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1
    
  3. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  4. Run the PowerShell command to install Gateway. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

  5. Ensure that the user identified in Get Application Pool User has Full control access to the Gateway folder created in Create New Web Application:

    1. Navigate to C:\inetpub\wwwroot\Cortex\.
    2. Right-click the Gateway folder and click Properties.
    3. In the Gateway Properties dialog, click the Security tab.
    4. Click the user identified in Get Application Pool User within the Group or user names section.
    5. In the Permissions section, ensure the user has Full control checked. If not:
      1. Click the Edit... button.
      2. Select the user identified in Get Application Pool User within the Group or user names section.
      3. In the Permissions section, check Full control.
      4. Click OK, then wait for Windows Security to update the security information to the folder.
      5. Click OK.
  6. Start the Gateway application pool:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Start.
  7. Once the application pool has been started, the site will be available on <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Setup Gateway

3.1.1.1.5 - Setup Gateway

Information about setting up Cortex Gateway for first-time use.

Setup Gateway

This guide describes how to setup Gateway. Please ensure that Install Web Application Server has been completed before taking these steps.

Gateway Initial Setup

Log on to Gateway and run through the setup wizard:

  1. Open a supported web browser and navigate to <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

    If an error message is displayed in the browser, wait a few minutes and refresh the page as it is possible that the website was still starting.

  2. Log on using the default credentials that Gateway deploys with:

    Username: administrator

    Password: Adm1n1strat0r

  3. On a newly installed system, you will be presented with a Setup Wizard at this point, which will guide you through some basic configuration steps:

  4. Follow the steps in the setup wizard to configure the relevant areas:

    Account Details

    1. Click Next Step:

      Initial Setup Screen

    2. Enter an email address for the Administrator and click Next Step:

      Administrator Details Screen

    3. Change the Administrator password to a unique, secret password and click Next Step:

      Change Password Screen

    LDAP Connection

    1. Enter the details of your Active Directory server and provide a Username and Password for a user with read access to it:

      A connection to an Active Directory server must be established in order to assign authorisation rights to users.

      1. In the Server field, enter the Hostname, FQDN or IP Address of the Active Directory server that Gateway should use to authenticate and authorise users.
      2. In the Port field, enter the port number of the Active Directory server. The well-known port for LDAP traffic is 389; if SSL encryption is used, the well-known port is 636.
      3. If an SSL connection is to be used, tick the box Use SSL.
      4. In the Username field, enter a valid username of a user that has read permissions for the Active Directory server.
      5. In the Password field, enter the password of the user entered in the previous step.
      6. To reduce the scope of any Active Directory searches, add one or more base DNs (Distinguished Names). For each base DN click Add and enter the full LDAP path e.g CN=group, OU=organisational unit, DC=domain, DC=com. These will be used as the roots of any Active Directory searches performed. For more information about distinguished names see https://msdn.microsoft.com/en-us/library/aa366101(v=vs.85).aspx.
    2. Click Test Connection to validate the connection and the user credentials entered and click Next Step.

    LDAP Connection Screen

    LDAP Authorisation

    1. If the authorisation grid fails to load first time round, click Retry.

    2. Assign access permissions to Active Directory groups:

      To allow users to access the various roles within Gateway, it is first necessary to assign them the appropriate access rights. Gateway currently supports four roles, but only two are relevant for Cortex Innovation:

      • Admin
      • Studio

      To give a user access to a role, set access for a group or Organisational Unit (OU) that the user is a member of:

      1. Expand the groups or OUs, or search for the group or OU, to be assigned one or more roles.
      2. Check the relevant roles for each group. Checking a parent group will cascade the setting to all child groups.

      LDAP Authorisation Screen

    3. Click Complete Setup to commit the changes.

    4. To test the permissions, log out as Administrator and then log in as a user with Studio permissions.

Configure the Gateway Databases to use Transparent Data Encryption

Once Gateway has been configured, if you wish to encrypt the databases using Transparent Data Encryption for improved security, this should now be performed by following the steps in Configuring TDE.

Next Steps?

  1. Try it out

3.1.1.1.6 - Try it out

Information about trying out Cortex Innovation for the first time.

Try it out

This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that Setup Gateway has been completed before taking these steps.

Test Debugging Flows

Test the platform by creating a new flow and executing it using the following steps:

  1. Click on the Flows charm, then the + button and click Group to open a dialog.
  2. Enter a name for the group, configure the Permission Groups and click OK to create the group.
  3. Click on the group to open it (refresh the page if it does not appear).
  4. Inside the group, click the + button again and click on Flow to open a dialog. If the menu item is not present, it means that the FeatureFlags in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway. See Troubleshooting for more information.
  5. Enter a name for the flow, configure the Permission Groups and click OK to create the flow.
  6. The flow should be displayed with a start flow block and end flow block. A list of block palettes should be displayed down the left hand side:

    New Flow - Number of palettes may differ

    If the blocks in the flow do not display or the palettes are not visible, see Troubleshooting for more information.
  7. Add a Set Variable block and connect it between the start and end blocks.
  8. Click the Set Variable block to open the Property Editor.
  9. Set the Value property to the expression DateTimeOffset.Now.
  10. Type Result into the Variable property and click Create Result.
  11. In the Variable Editor, set Is Output Variable? to true for the new Result variable.
  12. Set a breakpoint on the end block and start the flow. An execution token should appear, the Result variable should show the current time. If the token does not appear, try refreshing the page.
  13. Continue or stop the execution.
  14. Commit the flow.

Test Publishing Production Flows

  1. Log in to Gateway with a user that has the Admin role.
  2. Click on the Settings charm, then Packages.
  3. Click Add Package Definition. Enter a package name and select the new flow to add to the package. Click Save to save the new package.
  4. Click Publish. A success message should appear. If it doesn’t it means that either one or more of the parameters prefixed with Service Fabric in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway, or the Application Services aren’t healthy. See Troubleshooting for more information.

Test Executing Production Flows

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted)
  2. The request should return a JSON object with the output variables of the flow e.g. { "Output": "2022-03-09T07:35:16+0000" }.

  3. Cortex Innovation has now been verified and is ready to use.

3.1.1.2 - Single Server - Without HA

Information about installing Cortex Innovation on a single on-premise server without high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions.

Single server installations with HA are not recommended for the following scenarios:

  • Production installations that are required to scale and support HA

3.1.1.2.1 - Architecture

Information about the recommended Innovation platform architecture, including component descriptions.

Architecture

Components

Component Purpose Required/Optional Server Role
Cortex Gateway Web portal that hosts applications for creating automation solutions and managing their full life-cycle, including design, development, testing, deployment, monitoring, maintenance and ultimately end-of-life. Required Web Application Server
Cortex Studio Application hosted in Cortex Gateway that provides the graphical, low-code environment for developing, testing, versioning, publishing and managing the full life-cycle of automation solutions. Required Web Application Server
Cortex Flow Debugger Service Web application that allows flows to be debugged and executed. Used by Cortex Studio to debug flows and provide block information. Required Web Application Server
Cortex API Gateway Service Application Service that routes client requests to the correct Application Services. Required Application Server
Cortex Flow Execution Service Application Service that executes automation flows. Required Application Server
Cortex Block Packages A set of files which contain the blocks that users can use to build flows. Used by the Cortex Flow Debugger Service and the Cortex Flow Execution Service. Required Web Application Server, Application Server
Cortex Gateway Databases A set of databases created automatically by Gateway which are used for storing data related to user roles, flows, etc. Hopefully, we can remove the need for Gateway Databases in the next release. Required
(End of life)
Web Application Server
SQL Server Express or SQL Server Standard Required by Cortex Gateway for creating and storing the Gateway Databases. Hopefully, we can remove the need for SQL Server in the next release. Required
(End of life)
Web Application Server
Microsoft Service Fabric Distributed systems platform that hosts the Application Services where automation solutions are deployed to. Required Application Server
Microsoft Service Fabric Explorer Web portal for monitoring and managing the Service Fabric instance that automation solutions are deployed to. Required Application Server
Particular NServiceBus Messaging platform enabling scalable, reliable and flexible asynchronous messaging between Application Services. Required Application Server
Pivotal RabbitMQ Message broker used by the NServiceBus messaging platform to transport messages asynchronously between Application Services using publish/subscribe mechanism. Required Application Server
Erlang OTP Erlang run-time required by the RabbitMQ message broker. Required Application Server

Single Server Architecture

The following architecture requires 1 server:

1 Server Architecture Diagram

Next Steps?

  1. Prerequisites

3.1.1.2.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for a single server (as described in Architecture) are laid out in this guide. These must be considered before undertaking installation.

Hardware Requirements

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
Single Server
Application Server +
Web Application Server
1 4+ Recommended
Minimum
16+ Recommended
12 Minimum
150+ Recommended
100 Minimum
30+ free on installation drive
40+ free on %ProgramData% drive

Software Requirements

Server Role Windows Server1 SQL Server2 .Net PowerShell3 IIS4 Other Software
Single Server
Application Server +
Web Application Server
2019 (x64) Recommended
2016 (x64)
2019
2016
2016 Express
Framework 4.7.1 5.1 10.0.177635
10.0.143936
URL Rewrite Module 2.1
Microsoft Web Deploy 3.0 or later
Visual C++ Redistributable 2013 (x64)

Domain Requirements

The server must be on a domain and cannot be a domain controller.

DNS Requirements

The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server.

Licensing Requirements

A valid Cortex licence file and Cortex Innovation feature identifier must be procured from Cortex. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the server and it should contain that server’s fingerprint.

To get a licence file and feature identifier take the following steps:

  1. Copy the following template to a text file:

    Web Application/Application Server
    MachineID: 
    Fingerprint: 
    
    Please also include a suitable Cortex Innovation feature identifier.
    
  2. Extract Cortex Innovation 2022.9 - Licence Fingerprint Generator.zip.

  3. From that folder, copy Cortex.Licensing.FingerprintGeneration.exe to the server.

  4. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

    MachineID: SERVER
    Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
    
  5. Copy the output (machine identifier and fingerprint) to the Web Application/Application Server section of the text file created in the initial step. Note that the machine identifier can be changed to any string.

  6. Request a licence and feature identifier by raising a case in the Cortex Service Portal, including the contents of the text file containing all of the fingerprint and machine information in the body of the case.

  7. When the licence and feature identifier have arrived, copy the file Cortex.lic to %ProgramData%\Cortex\Licences on the Web Application Server, creating the Cortex and Licences folders if they don’t exist. Save the feature identifier for use when Installing Gateway.

Web Browser Requirements

Gateway supports the latest versions of the following browsers:

  • Chrome
  • Edge
  • Firefox

Certificate Requirements

An X.509 SSL certificate (standard or wildcard) should be used to:

  • Allow Application Services to identify themselves to clients such as Gateway.
  • Prevent unauthorised nodes from joining the single node cluster.
  • Connect to Service Fabric Explorer from the Application Server.
  • Connect to Gateway.
  • Allow Gateway to connect to the Flow Debugger Service.

The certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in one of the following formats, depending on the certificate type:
    • Standard certificates must use the standard format (e.g. CN=host.domain.com).
    • Wildcard certificates must use the wildcard format, pertaining to the domain of the server (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service.
  • Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1. It must include any additional host names that should be able to be used to access the API Gateway Service.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.
  • Key Usage extension must have a value of Digital Signature, Key Encipherment (a0).
  • Enhanced Key Usage must include Server Authentication and Client Authentication.

This file should be placed in a known location on the server. This location will be required when running the Application Server installation script.

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the server.

Additional Application Server Requirements

Filesystem Requirements

The server must use an NTFS filesystem.

Service Requirements

The following Windows Services must be running on the server:

  • Remote Registry
  • Windows Event Log
  • Performance Logs & Alerts

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on the server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the platform that Cortex Innovation is built upon.

Antivirus Exclusions

It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the server to reduce antivirus processing on Service Fabric artefacts:

Folder Exclusions:

  • %ProgramFiles%\Microsoft Service Fabric
  • %ProgramData%\SF
  • %ProgramData%\SF\Logs

Process Exclusions:

  • Fabric.exe
  • FabricHost.exe
  • FabricInstallerService.exe
  • FabricSetup.exe
  • FabricDeployer.exe
  • ImageBuilder.exe
  • FabricGateway.exe
  • FabricDCA.exe
  • FabricFAS.exe
  • FabricUOS.exe
  • FabricRM.exe
  • FileStoreService.exe

A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually.

If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist.

Port Requirements

Cortex Innovation and Microsoft Service Fabric require a range of firewall ports to be opened between the server and specific services.

If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in Port Requirements to open the correct ports.

The Cortex.Innovation.Test.PortUsage.ps1 script is provided during installation to test the ports on the server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible.

Additional Web Application Server Requirements

Security Requirements

Installation User

Domain users must be available to run the Application Pools for Gateway and Flow Debugger Service. These users must be given Log on as a service and Log on as a batch job permissions otherwise the Application Pools will not be able to run. Information about how to do this will be given during installation.

For Flow Debugger Service, the NETWORK SERVICE user can also be used.

Domain Requirements

For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported.

Supported versions of Active Directory are listed below:

Version Verified? Supported From Supported Until
Windows Server 2003 Cortex v2022.9 To be evaluated
Windows Server 2003 R2 Cortex v2022.9 To be evaluated
Windows Server 2008 Cortex v2022.9 To be evaluated
Windows Server 2008 R2 Cortex v2022.9 To be evaluated
Windows Server 2012 Cortex v2022.9 To be evaluated
Windows Server 2012 R2 Cortex v2022.9 To be evaluated
Windows Server 2016 Cortex v2022.9 To be evaluated
Windows Server 2019 Cortex v2022.9 To be evaluated
Windows Server 2022 Cortex v2022.9 To be evaluated

Next Steps?

  1. Install Application Server

  1. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

  2. SQL Server Express, Standard and Enterprise are supported. Other databases are not supported. Note that Transparent Data Encryption is not supported on SQL Server Express. ↩︎

  3. PowerShell 5.1 ships with Windows Server 2016 and 2019. ↩︎

  4. IIS is supported; other web servers, including IIS Express are not supported. ↩︎

  5. Ships as a windows role within Windows Server 2019. ↩︎

  6. Ships as a windows role within Windows Server 2016. ↩︎

3.1.1.2.3 - Install Application Server

Information about installing the Application Server.

Install Application Server

This guide describes how to install the Application Server components on the server. Please ensure that the Prerequisites have been read before starting this installation.

Make Installation Artefacts Available

  1. Copy the following artefacts to a folder on the server (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - App Services.zip
    • Cortex Innovation 2022.9 - App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - App Server Install Scripts.zip file to a folder with the same name.

Install Microsoft .NET Framework 4.7.1

Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.1 to be installed on the server.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

These are non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities.

Applying these measures may impact other applications running on your server. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes.

A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at SSL Best Practices.

The settings can be applied by running a script. Be aware that the server will be restarted when the script is run. Apply the settings by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.SSLBestPractices.ps1 script using the following command:

    .\Cortex.Innovation.Install.SSLBestPractices.ps1
    

    If -Override 0 has been specified no further steps need to be taken and you can move on to the next section when the server has restarted.

  4. To use all the recommended settings click Apply all to the first prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying.

  5. Restart the machine when the script asks.

Add Antivirus Exclusions

  1. If Windows Defender is not running on the server, ensure that the Antivirus Exclusions have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps:
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS name or fully qualified domain name of the server:

      .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

    5. A message will indicate that the script has completed successfully.

Check Port Usage

  1. To check all necessary ports are free, follow these steps.
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Test.PortUsage.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS name or fully qualified domain name of the server:

      .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

    5. If all ports are free, the script will report the following:

      All ports required by Cortex Innovation are free

      If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the Cortex.Innovation.Install.Config.json configuration file, in the Cortex Innovation 2022.9 - App Server Install Scripts folder, to use different ports. This will be used later during installation.

      The Cortex.Innovation.Test.PortUsage.ps1 script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, locate the Cortex.Innovation.Install.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1") `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1") `
        -UseSelfSignedCertificates `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt"
            
    Name Description
    AppServicesPath Configure this value with the location of the App Services zip file on the server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the server.
    ApiGatewayBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when installing Gateway.
    ApiGatewayBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows). This should be Cortex Encrypted.

    This value will be needed later, when installing Gateway.
    CustomerName A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer.
    ApplicationServerIPv4Addresses The IPv4 address of the server.
    ServerCertificatePath The local path of a .PFX certificate file on the server. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended). The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the Application Services.
    • Allowing Application Services to identify themselves to clients such as Gateway.
    • Preventing unauthorised nodes from joining the single node cluster.
    • Connecting to Service Fabric Explorer from each of the Application Servers.
    ServerCertificatePwd The password for the .PFX certificate file specified in ServerCertificatePath.

    This is only needed if installing with CA Certificates (Recommended).
    UseSelfSignedCertificates Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    SkipLoadBalancer Installs Application Services and required infrastructure without installing a load balancer.
    Credential The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.

    The ApiGatewayBasicAuthUserName and ApiGatewayBasicAuthPwd will be needed later, when installing Gateway.

  3. Save and close Cortex.Innovation.Install.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1 -WhatIf
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -WhatIf -AcceptEULA
    
  5. Run the PowerShell command to test the installation script.

  6. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  7. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ.

  8. Wait for the command to finish. It will display the output of the installation command without making any changes to the system.

  9. Check that there have been no errors in the script; these would appear in red in the console.

    If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them.

    If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

    If this does not work, please contact Cortex Service Portal for further assistance. The WhatIf script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with -WhatIf (e.g. Cortex.Innovation.Install.Config-WhatIf.json). This file can be provided when obtaining support.

Run Installation Script

  1. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1
    
  2. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  3. Run the PowerShell command to install HA Services and the required infrastructure.

  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  5. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from Cortex Service Portal. Press OK.

  6. Wait for the script to finish running. This should take approximately 10 minutes.

  7. Check that there have been no errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation.

    In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command:

    .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer
    

    If the errors do not give any instructions on how to rectify, see Troubleshooting During Installation for further information; if this does not help then please contact Cortex Service Portal for assistance.

Check Application Services

  1. Log on to the server.

  2. Import the certificate, used in the ServerCertificatePath parameter of the Configure Installation Script section, to your Current User certificate store. This can be achieved by double clicking on the certificate .PFX file and following the wizard.

    If using self-signed certificates, the certificate can be retrieved by using the Manage Computer Certificates tool in Windows to export the CortexServerCertificate from the Personal store and then importing it to the Current User store by double-clicking on it and following the wizard.

  3. Open a web browser.

  4. Navigate to https://server.domain.com:9080/Explorer, where server.domain.com is the fully qualified domain name of the server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    The screen should resemble that in the following figure:

    Healthy Service Fabric Explorer Cluster

    The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system.

    After expanding the application, clicking on any of the services should display a green circle and Status = Active:

    Healthy Service Fabric Explorer Service

    After expanding either of the services, clicking on any of the instances/partitions should display a green circle and Status = Ready:

    Healthy Service Fabric Explorer Instance

    Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and Status = Up:

    Healthy Service Fabric Explorer Node

    If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section.

    If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong.

    If no useful message can be seen here, the service log files may contain more information. These can be found on the server at:

    • %ProgramData%/Cortex/Cortex API Gateway Service
    • %ProgramData%/Cortex/Cortex Flow Execution Service

    If no solution can be found, please contact Cortex Service Portal for further assistance.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Install Web Application Server

3.1.1.2.4 - Install the Web Application Server

Information about installing the Web Application Server.

Install the Web Application Server

This guide describes how to install the Web Application Server components on the server. Please ensure that Install Application Server has been completed before starting this installation.

Make Installation Artefacts Available

  1. Copy the following artefacts to a folder on the server (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - Gateway.zip
    • Cortex Innovation 2022.9 - Flow Debugger Service.zip
    • Cortex Innovation 2022.9 - Web App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - Web App Server Install Scripts.zip zip file to a folder with the same name.

Install Prerequisites

Licensing

Ensure that a valid Cortex licence file named Cortex.lic exists on the server, in the location %ProgramData%\Cortex\Licences. If it does not, follow the instructions located at Licensing Requirements.

Install SQL Server or SQL Express

  1. Use one of the following installation guides to install SQL Server or SQL Server Express:

Install Microsoft .NET Framework 4.7.1

Gateway requires a minimum of Microsoft .NET Framework 4.7.1.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

Install Microsoft Web Deploy

  1. Check if Web Deploy is already installed by going to Control PanelProgramsPrograms and Features; if Web Deploy is already installed, it will be listed as Microsoft Web Deploy.
  2. If it is not installed, download Microsoft Web Deploy version 3.0 or later (WebDeploy_amd64_en-US.exe) to the server.
  3. Double-click the downloaded file to start the installation.
  4. Follow the installation wizard to install Web Deploy; on the Choose Setup Type page select Typical.

Install Visual C++ Redistributable

  1. Check if Visual C++ 2013 Redistributable (x64) is already installed by going to Control PanelProgramsPrograms and Features; if Visual C++ Redistributable is already installed, it will be listed as Microsoft Visual C++ 2013 Redistributable (x64).
  2. If it is not installed, download Visual C++ Redistributable 2013 (x64).
  3. Double-click the downloaded file to start the installation.
  4. Follow the installation wizard to install the Visual C++ Redistributable.

IIS Role Setup and Configuration

Install Internet Information Services (IIS)

Install the required features by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.WindowsFeatures.ps1 script using the following command, this may take a few minutes:

    .\Cortex.Innovation.Install.WindowsFeatures.ps1
    
  4. Check the output is as follows:

    Web-WebSockets is installed
    Web-Asp-Net45 is installed
    Web-Net-Ext45 is installed
    Web-ISAPI-Ext is installed
    Web-ISAPI-Filter is installed
    Net-Framework-45-Core is installed
    Net-Framework-45-ASPNET is installed
    Web-Default-Doc is installed
    Web-Dir-Browsing is installed
    Web-Http-Errors is installed
    Web-Static-Content is installed
    Web-Http-Logging is installed
    Web-Http-Redirect is installed
    Web-Request-Monitor is installed
    Web-Stat-Compression is installed
    Web-Dyn-Compression is installed
    Web-Filtering is installed
    Web-Windows-Auth is installed
    Web-Mgmt-Console is installed
    Web-Mgmt-Service is installed
    

Register and Allow .NET CLR v4.0.30319 with IIS

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Run the following command:

    Dism /online /enable-feature /featurename:IIS-ASPNET45 /all
    
  3. Once PowerShell confirms that it has finished installing .NET CLR v4.0.30319, close the PowerShell window.

Install URL Rewrite Module

The URL Rewrite IIS Manager module is required to enable web applications on your server to rewrite URLs. This is needed to allow HTTP URLs to redirect to the equivalent HTTPS ones.

To install the URL Rewrite module take the following steps:

  1. In the left-hand pane of Internet Information Service (IIS) Manager, select the server node.
  2. Ensure that there is an icon with the title URL Rewrite under the IIS feature section:

    Url Rewrite Module Icon

  3. If there is an icon, URL Rewrite module is installed and no further steps are required.
  4. If there is no icon, the module is not installed and the following steps must be taken:
    1. Download the URL Rewrite module installer.
    2. Double-click on the installer file to run it.
    3. Follow the wizard to complete the installation.
    4. After successfully installing, close and reopen IIS Manager. The URL Rewrite icon should now be visible.

Add HTTPS Firewall Rule

If any firewall is running on the server, it must be configured to allow communication inbound via TCP on the port configured for HTTPS (usually 443). See Configure Firewalls for information about adding rules to Windows Firewall.

Create Web Site

Gateway and Flow Debugger Service can either be installed to an existing web site or a newly created web site. If you are installing into an existing web site skip to Configure Web Site.

The steps to create a new web site are:

  1. In Windows File Explorer, navigate to the default IIS folder (usually %SystemDrive%\inetpub\wwwroot, e.g. C:\inetpub\wwwroot).
  2. Ensure there is a folder called Cortex; if not create it.
  3. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  4. Right-click the Sites node under the server and select Add Website….
  5. Set the Site name to Cortex.
  6. Set the Physical path to the folder created above (e.g. C:\inetpub\wwwroot\Cortex), by clicking on the ellipses , selecting the appropriate directory and clicking OK.
  7. Click OK. If an existing site is already using the specified port, a warning will be displayed. Either click No and change the Port in the Add Website dialog, or click Yes and stop the other website.

Configure Web Site

The web site which the Gateway and Flow Debugger Service are installed under requires additional configuration.

Configure HTTPS

Both the Gateway and Flow Debugger Service should be configured to use HTTPS:

  1. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  2. Expand the Sites node under the server.
  3. Right-click the web site where Gateway will be installed and select Edit Bindings….
  4. Click Add…
  5. Set Type to https.
  6. Set the appropriate Port number (typically 443). The Host name box can be left blank.
  7. Select the SSL certificate that was used when installing the Application Server. If self-signed certificates were used, this will have the subject CN=CortexServerCertificate.
  8. Click OK. If an existing site is already using the specified SSL port, a warning will be displayed. Either click No and change the Port in the Add Site Binding dialog, or click Yes and stop the other website.
  9. It is recommended to remove the http site binding.

Install Flow Debugger Service

Get Application Pool User

A domain user account is required for the Flow Debugger Service web application pool and must be created prior to performing the installation. In line with best practices, this account should not be used for any purposes other than those specified for the Flow Debugger Service. Alternatively, the NETWORK SERVICE user may also be used.

This user must currently have access to the default NuGet directory, in order to load block packages correctly. To add permissions for the user take the following steps:

  1. Navigate to %SystemRoot%\System32\config\systemprofile\AppData\Roaming\ and create a new folder named NuGet if one does not exist.
  2. Right-click on the NuGet folder and click Properties.
  3. In the dialog, click the Security tab.
  4. Click the Edit... button.
  5. Click the Add... button.
  6. Enter the username of the application pool user and click OK.
  7. In the Permissions section at the bottom, check Full control
  8. Click OK.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.FlowDebuggerService.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -UseSelfSignedCertificates `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    Name Description
    FlowDebuggerServicePath Configure this value with the location of the Flow Debugger Service zip file on the server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the server.
    FlowDebuggerBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when installing Gateway.
    FlowDebuggerBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when installing Gateway.
    UseSelfSignedCertificates Enables Flow Debugger Service to communicate with Gateway using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    Credential The credentials of the user that will be used to run the Debugger application pool in IIS.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.FlowDebuggerService.ps1.

Run Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.FlowDebuggerService.ps1
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  5. Run the PowerShell command to install the Flow Debugger Service.

  6. A credentials prompt will appear. Enter the credentials of the user that should run the Debugger application pool in IIS. If using the NETWORK SERVICE user, enter any user as the username and leave the password blank; the NETWORK SERVICE user will need to be selected in the final step.

  7. Wait for the script to finish running. This should take approximately 2 minutes.

  8. An error may have appeared saying:

    The Windows Process Activation Service service is not started.
    

    This can be ignored.

  9. Check that there have been no other errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation.

    If the errors do not give any instructions on how to rectify, please contact Cortex Service Portal for further assistance.

  10. If using NETWORK SERVICE for the application pool user:

    1. Open Internet Information Services (IIS) Manager.
    2. On the left, expand the server node.
    3. Click Application Pools.
    4. Right-click on the Debugger application pool and select Advanced Settings....
    5. In the Advanced Settings dialog, click on Identity and then click the ellipses (...).
    6. In the Application Pool Identity dialog, select Built-in account, then select NetworkService from the drop-down, then click OK.
    7. Right-click on the Debugger application pool and click Recycle....

Install Gateway

Get Application Pool User

A domain user account is required for the Gateway web application pool and must be created prior to performing the installation below.

This user account is required to enable Gateway to access the Cortex database, with the following roles:

  • dbcreator
  • public

To add roles to database users take the following steps:

  1. Open SQL Server Management Studio on the server and log in.

  2. Expand the server node, then Security then Logins.

  3. If the user that will run the Gateway application pool is not in the list of logins, take the following steps, otherwise skip to step 4:

    1. Right-click the Logins node and click New Login....
    2. Enter the application pool user in the Login name box.
    3. On the left pane, click Server Roles.
    4. Check public and dbcreator
    5. Click OK.
  4. If the user that will run the Gateway application pool is in the list of logins, take the following steps:

    1. Right-click on the application pool user.
    2. Click Properties.
    3. On the left pane, click Server Roles.
    4. Check public and dbcreator.
    5. Click OK.

In line with best practices, this account should not be given administrator rights, nor should it be used for any purposes other than those specified for Gateway.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Create Gateway Application Pool

  1. Open Internet Information Services (IIS) Manager.
  2. Select and right-click the Application Pools node under the server and select Add Application Pool…
  3. Set Name to Cortex Gateway.
  4. Ensure that the .NET CLR version is set to .NET CLR Version v4.0.30319 (This may be configured by default).
  5. Ensure that the Managed pipeline mode is set to Integrated (This may be configured by default).
  6. Click OK
  7. Right click on the created application pool and select Advanced Settings…
  8. Click the ... next to Identity (under Process Model) to open a dialog, then select Custom Account and Set....
  9. Enter the username and password for the user identified in Get Application Pool User.
  10. Click OK to close the Set Credentials dialog.
  11. Click OK to close the Application Pool Identity dialog.
  12. Click OK to close the Advanced Settings dialog.

Create New Web Application

  1. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  2. Right-click on the site the application should be installed under and select Add Application…
  3. Set the Alias to gateway. This must be lowercase.
  4. Click Select… and from the Application pool dropdown select the Cortex Gateway application pool and click OK.
  5. Set the Physical path to C:\inetpub\wwwroot\Cortex\Gateway by clicking on the ellipses and selecting the appropriate directory. Create the C:\inetpub\wwwroot\Cortex\Gateway directory if it does not already exist.
  6. Click OK.

Configure IIS Site Redirect to the Specified Web Application (Optional)

If the site hosting the Gateway web application is a newly created Cortex site or an existing site that doesn’t have its own content, it is recommended to redirect the site URL to the gateway web application URL, e.g. https://FullyQualifiedDomainName to https://FullyQualifiedDomainName/gateway.

  1. Open Internet Information Services (IIS) Manager.
  2. Select the site hosting the gateway web application and from IIS settings double-click the HTTP Redirect icon.
  3. Click the check box Redirect requests to this destination.
  4. Enter https://FullyQualifiedDomainName/gateway, replacing FullyQualifiedDomainName with the FQDN of the server.
  5. In the Redirect Behaviour section, click Only redirect requests to content in this directory (not subdirectories).
  6. In Actions click the Apply button.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.Gateway.ps1 script and open it with a text editor.

  2. Configure the script according to the details given below:

    .\Cortex.Install.Gateway.ps1 `
    -GatewayPackagePath "C:\Install\Cortex Innovation 2022.9 - Gateway.zip" `
    -GatewayApplicationIISPath "Cortex\gateway" `
    -ModelDBContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb;Integrated Security=True;MultipleActiveResultSets=True" `
    -AuthContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb.Auth;Integrated Security=True;MultipleActiveResultSets=True" `
    -SignalRContextConnectionString "Data Source=localhost;Initial Catalog=CortexWeb.SignalR;Integrated Security=True;MultipleActiveResultSets=True" `
    -FeatureFlags "InnovationId" `
    -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" `
    -ServiceFabricUsingSelfSignedCertificates $false `
    -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" `
    -ServiceFabricApiGatewayBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerEndpoint "https://server.domain.com/debugger/api/" `
    -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" `
    -DotNetFlowDebuggerBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerUsingSelfSignedCertificates $false `
    -Test:$Test `
    -AcceptEULA:$AcceptEula `
    *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt"
    
    Name Description
    GatewayPackagePath Configure this value with the location of the Cortex Innovation 2022.9 - Gateway.zip file on the installation server.
    GatewayApplicationIISPath Change to the correct Site Name/Application if either was modified from the defaults (Cortex/gateway) when creating the website or application.
    ModelDBContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance.

    This will set the ModelDBContextConnectionString value in the Gateway web.config.
    AuthContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance.

    This will set the AuthContextConnectionString value in the Gateway web.config.
    SignalRContextConnectionString If SQL Server was installed as the default instance, change the Data Sourcein the connection string to localhost.

    If SQL Server was installed as a named instance, change it to .\{instanceName} replacing {instanceName} with the name of the instance.

    This will set the SignalRContextConnectionString value in the Gateway web.config.
    FeatureFlags Replace InnovationId with the Cortex Innovation feature identifier, which should have been provided by Cortex when fulfilling the Licensing Requirements, if it wasn’t it should be requested using Cortex Service Portal.

    This will set the FeatureFlags value in the Gateway web.config.
    ServiceFabricApiGatewayEndpoint Replace server.domain.com with the fully qualified domain name of the server. The port should be specified as 8722 and there must be a trailing slash, e.g. https://server.domain.com:8722/.

    This will set the ServiceFabricApiGatewayEndpoint value in the Gateway web.config.
    ServiceFabricUsingSelfSignedCertificates Configure the value as $false if you used valid CA certificates when installing the Application Server, $true if you used self-signed certificates.

    This will set the ServiceFabricUsingSelfSignedCertificates value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthUsername This must be changed if you used a non-default ApiGatewayBasicAuthUserName when installing the Application Server; if so, this value must be configured to the one used.

    This will set the ServiceFabricApiGatewayBasicAuthUsername value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthPassword This must be changed if you used a non-default ApiGatewayBasicAuthPassword when installing the Application Server; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will set the ServiceFabricApiGatewayBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerEndpoint Replace server.domain.com with the fully qualified domain name of the Web Application Server.

    This will set the DotNetFlowDebuggerEndpoint value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthUsername This must be changed if you used a non-default FlowDebuggerBasicAuthUserName when installing the Flow Debugger Service; if so, this value must be configured to the one used.

    This will set the DotNetFlowDebuggerBasicAuthUsername value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthPassword This must be changed if you used a non-default FlowDebuggerBasicAuthPassword when installing the Flow Debugger Service; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will set the DotNetFlowDebuggerBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerUsingSelfSignedCertificates Configure the value as $false if you are using valid CA certificates to secure the site containing Gateway and Flow Debugger Service, $true if using self-signed certificates.

    This will set the DotNetFlowDebuggerUsingSelfSignedCertificates value in the Gateway web.config.
    Test This does not need to be changed, it will be set at a later stage.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.Gateway.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1 -Test
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -Test -AcceptEULA
    
  5. Run the PowerShell command to test the configuration. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

Run Installation Script

  1. Ensure the Gateway application pool is stopped:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Stop.
  2. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1
    
  3. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  4. Run the PowerShell command to install Gateway. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

  5. Ensure that the user identified in Get Application Pool User has Full control access to the Gateway folder created in Create New Web Application:

    1. Navigate to C:\inetpub\wwwroot\Cortex\.
    2. Right-click the Gateway folder and click Properties.
    3. In the Gateway Properties dialog, click the Security tab.
    4. Click the user identified in Get Application Pool User within the Group or user names section.
    5. In the Permissions section, ensure the user has Full control checked. If not:
      1. Click the Edit... button.
      2. Select the user identified in Get Application Pool User within the Group or user names section.
      3. In the Permissions section, check Full control.
      4. Click OK, then wait for Windows Security to update the security information to the folder.
      5. Click OK.
  6. Start the Gateway application pool:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Start.
  7. Once the application pool has been started, the site will be available on <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Setup Gateway

3.1.1.2.5 - Setup Gateway

Information about setting up Cortex Gateway for first-time use.

Setup Gateway

This guide describes how to setup Gateway. Please ensure that Install Web Application Server has been completed before taking these steps.

Gateway Initial Setup

Log on to Gateway and run through the setup wizard:

  1. Open a supported web browser and navigate to <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

    If an error message is displayed in the browser, wait a few minutes and refresh the page as it is possible that the website was still starting.

  2. Log on using the default credentials that Gateway deploys with:

    Username: administrator

    Password: Adm1n1strat0r

  3. On a newly installed system, you will be presented with a Setup Wizard at this point, which will guide you through some basic configuration steps:

  4. Follow the steps in the setup wizard to configure the relevant areas:

    Account Details

    1. Click Next Step:

      Initial Setup Screen

    2. Enter an email address for the Administrator and click Next Step:

      Administrator Details Screen

    3. Change the Administrator password to a unique, secret password and click Next Step:

      Change Password Screen

    LDAP Connection

    1. Enter the details of your Active Directory server and provide a Username and Password for a user with read access to it:

      A connection to an Active Directory server must be established in order to assign authorisation rights to users.

      1. In the Server field, enter the Hostname, FQDN or IP Address of the Active Directory server that Gateway should use to authenticate and authorise users.
      2. In the Port field, enter the port number of the Active Directory server. The well-known port for LDAP traffic is 389; if SSL encryption is used, the well-known port is 636.
      3. If an SSL connection is to be used, tick the box Use SSL.
      4. In the Username field, enter a valid username of a user that has read permissions for the Active Directory server.
      5. In the Password field, enter the password of the user entered in the previous step.
      6. To reduce the scope of any Active Directory searches, add one or more base DNs (Distinguished Names). For each base DN click Add and enter the full LDAP path e.g CN=group, OU=organisational unit, DC=domain, DC=com. These will be used as the roots of any Active Directory searches performed. For more information about distinguished names see https://msdn.microsoft.com/en-us/library/aa366101(v=vs.85).aspx.
    2. Click Test Connection to validate the connection and the user credentials entered and click Next Step.

    LDAP Connection Screen

    LDAP Authorisation

    1. If the authorisation grid fails to load first time round, click Retry.

    2. Assign access permissions to Active Directory groups:

      To allow users to access the various roles within Gateway, it is first necessary to assign them the appropriate access rights. Gateway currently supports four roles, but only two are relevant for Cortex Innovation:

      • Admin
      • Studio

      To give a user access to a role, set access for a group or Organisational Unit (OU) that the user is a member of:

      1. Expand the groups or OUs, or search for the group or OU, to be assigned one or more roles.
      2. Check the relevant roles for each group. Checking a parent group will cascade the setting to all child groups.

      LDAP Authorisation Screen

    3. Click Complete Setup to commit the changes.

    4. To test the permissions, log out as Administrator and then log in as a user with Studio permissions.

Configure the Gateway Databases to use Transparent Data Encryption

Once Gateway has been configured, if you wish to encrypt the databases using Transparent Data Encryption for improved security, this should now be performed by following the steps in Configuring TDE.

Next Steps?

  1. Try it out

3.1.1.2.6 - Try it out

Information about trying out Cortex Innovation for the first time.

Try it out

This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that Setup Gateway has been completed before taking these steps.

Test Debugging Flows

Test the platform by creating a new flow and executing it using the following steps:

  1. Click on the Flows charm, then the + button and click Group to open a dialog.
  2. Enter a name for the group, configure the Permission Groups and click OK to create the group.
  3. Click on the group to open it (refresh the page if it does not appear).
  4. Inside the group, click the + button again and click on Flow to open a dialog. If the menu item is not present, it means that the FeatureFlags in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway. See Troubleshooting for more information.
  5. Enter a name for the flow, configure the Permission Groups and click OK to create the flow.
  6. The flow should be displayed with a start flow block and end flow block. A list of block palettes should be displayed down the left hand side:

    New Flow - Number of palettes may differ

    If the blocks in the flow do not display or the palettes are not visible, see Troubleshooting for more information.
  7. Add a Set Variable block and connect it between the start and end blocks.
  8. Click the Set Variable block to open the Property Editor.
  9. Set the Value property to the expression DateTimeOffset.Now.
  10. Type Result into the Variable property and click Create Result.
  11. In the Variable Editor, set Is Output Variable? to true for the new Result variable.
  12. Set a breakpoint on the end block and start the flow. An execution token should appear, the Result variable should show the current time. If the token does not appear, try refreshing the page.
  13. Continue or stop the execution.
  14. Commit the flow.

Test Publishing Production Flows

  1. Log in to Gateway with a user that has the Admin role.
  2. Click on the Settings charm, then Packages.
  3. Click Add Package Definition. Enter a package name and select the new flow to add to the package. Click Save to save the new package.
  4. Click Publish. A success message should appear. If it doesn’t it means that either one or more of the parameters prefixed with Service Fabric in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway, or the Application Services aren’t healthy. See Troubleshooting for more information.

Test Executing Production Flows

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted)
  2. The request should return a JSON object with the output variables of the flow e.g. { "Output": "2022-03-09T07:35:16+0000" }.

  3. Cortex Innovation has now been verified and is ready to use.

3.1.1.3 - Advanced Setup

Supporting information about installing Cortex Innovation with non-default configurations.

3.1.1.3.1 - Advanced Application Server and Load Balancer Configuration Changes

Information about installing Cortex Innovation with non-default installation values.

Advanced Application Server and Load Balancer Configuration Changes

Advanced configuration (such as port changes) can be undertaken by taking the following steps before running the PowerShell script. Some values will be modified by the script and they will take precedence, but those parameters can be removed from the script and this file used entirely if required.

Multiple Server With HA

  1. In the Cortex Innovation 2022.9 - Installation Scripts folder, locate the file Cortex.Innovation.Install.Config.json and open it with a text editor.

  2. Change the configuration file according to your cluster, referring to the following example and details:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    
    {
      "customers": [
        {
          "name": "Customer1",
          "isPrimary": true,
          "rules": {
            "clientConnectionEndpointPort": "8001",
            "clusterConnectionEndpointPort": "8002",
            "leaseDriverEndpointPort": "8003",
            "serviceConnectionEndpointPort": "8004",
            "httpGatewayEndpointPort": "9080",
            "reverseProxyEndpointPort": "9081",
            "applicationPorts": "10010-10500",
            "ephemeralPorts": "10501-20000"
          },
          "loadBalancer": {
            "installDirectory": "%ProgramData%\\loadbalancer",
            "iPAddress": "192.168.20.178",
            "loadBalancerSnmpPort": "162",
            "snmpReceiverServicePort": "10001",
            "loadBalancerTlsPort": "443",
            "apiGatewayServicePort": "8722",
            "adminCertificate": "loadBalancerCertificate"
          },
          "servers": [
            {
              "serverName": "app-server1",
              "iPAddress": "192.168.1.1"
            },
            {
              "serverName": "app-server2",
              "iPAddress": "192.168.1.2"
            },
            {
              "serverName": "app-server3",
              "iPAddress": "192.168.1.3"
            }
          ]
        }
      ],
      "servers": {
        "app-server1": {
          "faultDomain": "fd:/fd1",
          "serverCertificate": "serverCert"
        },
        "app-server2": {
          "faultDomain": "fd:/fd2",
          "serverCertificate": "serverCert"
        },
        "app-server3": {
          "faultDomain": "fd:/fd3",
          "serverCertificate": "serverCert"
        }
      },
      "rules": {
        "windowsSmbRemoteRegistry": [
          "135",
          "137",
          "138",
          "139",
          "445"
        ],
        "rabbitMqAmqpPorts": [
          "5671"
        ],
        "rabbitMqEpmdPort": "4369",
        "rabbitMqErlangDistributionClientPorts": "35672-35682",
        "rabbitMqErlangDistributionServerPort": "25672",
        "rabbitMqManagementApiPort": "15671"
      },
      "serverCertificates": {
        "serverCert": {
          "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx",
          "pfxCertificatePassword": "pfxPassword",
          "pemRootCertificatePath": ""
        }
      },
      "adminCertificates": {
        "loadBalancerCert": {
          "pfxCertificatePath": "C:\\Certificates\\lbCert.pfx",
          "pfxCertificatePassword": "pfxPassword",
          "pemRootCertificatePath": ""
        }
      }
    }
    Line Description
    4 A name identifying the platform being installed. This should have no spaces or symbols. It will be appended to the node names that are displayed in the Service Fabric management tool.
    16-24 If the bundled load balancer is not being used, delete these lines
    17 A local empty or non-existent directory on the load balancer server that the load balancer can be installed in. The directory path will be created if it does not exist. The installation user must have permissions to create and write to directories here. Ensure that all backslashes are escaped with another backslash. Environment variables may be used.
    18 The IPv4 address of the server that the load balancer should run on.
    21 The port that the HTTPS load balancer server should run on. This port should not be in use by anything else.
    22 The port that the API Gateway Service is running on the Application Servers. This should be 8722.
    23 The name of a certificate entry in the adminCertificates section. If this line is removed, an auto-generated self-signed certificate will be used.
    27, 31, 35 The short computer names of the Application Servers. These must not contain the domain. The installation will be run on the first of these nodes.
    28, 32, 36 The respective IPv4 addresses of the Application Servers.
    42, 46, 50 These keys should be changed to the computer names of the Application Servers to match those on lines 26, 30 and 24
    44, 48, 52 The name of a certificate entry in the serverCertificates section. This should be the same for all Application Servers. If these lines are removed, an auto-generated self-signed certificate will be used. Self-signed certificates are not recommended for production systems.
    73-75 Skip configuring these lines if self-signed certificates are being used.
    80-82 Skip configuring these lines if self-signed certificates are being used or if the bundled load balancer is not being used.
    74 This is the local path of a .PFX certificate file on the first Application Server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used.
    75 The password used to secure the .PFX file.
    76 This only needs to be used if the installation has failed due to a missing root certificate. See Troubleshooting Root Certificate Error for information.
    81 This is the local path of a .PFX certificate file on the first Application Server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used.
    82 The password used to secure the .PFX file.
    83 This only needs to be used if the installation has failed due to a missing root certificate. See Troubleshooting Root Certificate Error for information.
  3. Save and close the config file.

Single Server Without HA

  1. In the Cortex Innovation 2022.9 - Installation Scripts folder, locate the file Cortex.Innovation.Install.Config.json and open it with a text editor.

  2. Change the configuration file according to your cluster, referring to the following example and details:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    
    {
      "customers": [
        {
          "name": "Customer1",
          "isPrimary": true,
          "rules": {
            "clientConnectionEndpointPort": "8001",
            "clusterConnectionEndpointPort": "8002",
            "leaseDriverEndpointPort": "8003",
            "serviceConnectionEndpointPort": "8004",
            "httpGatewayEndpointPort": "9080",
            "reverseProxyEndpointPort": "9081",
            "applicationPorts": "10010-10500",
            "ephemeralPorts": "10501-20000"
          },
          "servers": [
            {
              "serverName": "app-server1",
              "iPAddress": "192.168.1.1"
            }
          ]
        }
      ],
      "servers": {
        "app-server1": {
          "faultDomain": "fd:/fd1",
          "serverCertificate": "serverCert"
        }
      },
      "rules": {
        "windowsSmbRemoteRegistry": [
          "135",
          "137",
          "138",
          "139",
          "445"
        ],
        "rabbitMqAmqpPorts": [
          "5671"
        ],
        "rabbitMqEpmdPort": "4369",
        "rabbitMqErlangDistributionClientPorts": "35672-35682",
        "rabbitMqErlangDistributionServerPort": "25672",
        "rabbitMqManagementApiPort": "15671"
      },
      "serverCertificates": {
        "serverCert": {
          "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx",
          "pfxCertificatePassword": "pfxPassword",
          "pemRootCertificatePath": ""
        }
      }
    }
    Line Description
    4 A name identifying the platform being installed. This should have no spaces or symbols. It will be appended to the node names that are displayed in the Service Fabric management tool.
    18 The short computer names of the node. This must not contain the domain. The installation will be run on the this node.
    19 The IPv4 address of the node.
    25 This key should be changed to the computer names of the node to match that on line 18
    27 The name of a certificate entry in the serverCertificates section. If this line is removed, an auto-generated self-signed certificate will be used. Self-signed certificates are not recommended for production systems.
    48-50 Skip configuring these lines if self-signed certificates are being used.
    48 This is the local path of a .PFX certificate file on the server, containing a full chain certificate with private key. Ensure that all backslashes are escaped with another backslash. Environment variables cannot be used.
    49 The password used to secure the .PFX file.
    50 This only needs to be used if the installation has failed due to a missing root certificate. See Troubleshooting Root Certificate Error for information.
  3. Save and close the config file.

3.1.1.3.2 - Configure Firewalls

Information about configuring Firewalls, e.g. adding rules.

Configure Firewalls

Add Inbound Rules to Windows Firewall

To set up inbound rules for Windows Firewall take the following steps for each rule that you want to add:

  1. Navigate to StartAdministrative ToolsWindows Firewall with Advanced Security.
  2. In the left-hand panel, click on the Inbound Rules node.
  3. In the right-hand panel, click on New Rule.
  4. In the New Inbound Rule Wizard, select the Port option then click on the Next > button.
  5. Select either TCP or UDP depending on the rule that is being made.
  6. Select Specific local ports.
  7. Enter the required ports in a comma separated list (e.g. 443, 80) in the text box and press Next >.
  8. Select Allow the connection then click Next >.
  9. Click Next > again, then add an identifiable name for the rule
  10. Click Finish.

3.1.1.3.3 - Configure the Gateway Databases to use Transparent Data Encryption

Information about configuring Gateway Databases to use Transparent Data Encryption.

Configure the Gateway Databases to use Transparent Data Encryption

Once the Gateway Setup steps have been completed, if you wish to encrypt the databases using Transparent Data Encryption (TDE) for improved security, this should now be performed.

Enabling TDE on the databases ensures that the data is encrypted on disk. The process to do this requires that you:

  • Create a master key in the master database with a strong password. This password must be remembered and/or saved in a secure location to enable decryption of the database later.
  • Create a certificate within SQL Server.
  • Backup the certificate and store it in a secure location. If a database needed to be restored elsewhere for any reason the certificate will need to be imported to the new server.
  • Create a database encryption key in each user database to be encrypted.
  • Enable encryption on the database.

To enable TDE on the suite of Gateway Databases you should complete the following steps:

  1. Open SQL Server Management Studio.

  2. Open the Cortex.Install.TDE.sql script included within the Cortex Innovation 2022.9 - Web App Server Install Scripts folder.

  3. Set the @sPassword parameter value to a password that you wish to use.

  4. You can change the names of the certificate and the name of the master key by changing the @sCertName and @sKeyName parameters if you so wish.

  5. You can change the location that the certificate and key are backed up to by changing the value of the @sBackupLocation parameter.

    The location must already exist, and there must not be any files within the specified location with the same name as the certificate or master key names that have been specified.

    The user that this script will be executed as must also have write permissions to this location.

  6. Once the parameters have been set appropriately you should now save the script.

    We recommended that the modified script is saved out to file (taking care to observe your own organisation’s security policies for password management), before it is executed. This may help facilitate the support process if anything goes wrong.

  7. Click Execute to run the script. It may take several minutes to execute depending on the size of the databases.

  8. Once the script has completed successfully, you should move the backed-up certificate and master key to a secure location and the password specified should also be stored securely.

3.1.1.3.4 - Create Self-Signed Certificates

Information about creating and installing self-signed certificates.

Create Self-Signed Certificates

Self-signed certificates should be generated using OpenSSL which is bundled in the Cortex Web App Server Install Scripts:

Setup OpenSSL in PowerShell

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Make a directory in which to store the certificates by running the following command, changing the path as required:

    mkdir C:\Certificates
    
  3. Navigate PowerShell to inside the certificates folder created above, using the following command, modifying the path as necessary:

    cd "C:\Certificates"
    
  4. Temporarily add OpenSSL to the Path environment variable of your system by running the following command, modifying the path according to the location of openssl.exe in the installation scripts on the machine:

    $env:PATH += ";C:\Cortex Innovation 2022.9 - Web App Server Install Scripts\OpenSSL"
    

Generate the Root CA Certificate

  1. Create the Root CA private key by running the following command:

    openssl genrsa -out cortexCA.key 4096
    
  2. Generate the Root CA certificate signed with the private key:

    1. Copy the following text into a text editor:

      RANDFILE		= .rnd
      [ ca ]
      default_ca	= CA_default	# The default ca section
      [ CA_default ]
      # Directory and file locations.
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md        = sha256
      policy            = policy_strict
      [ policy_strict ]
      # The root CA should only sign intermediate certificates that match.
      # See the POLICY FORMAT section of `man ca`.
      countryName             = match
      stateOrProvinceName     = match
      organizationName        = match
      organizationalUnitName  = optional
      commonName              = supplied
      emailAddress            = optional
      [ req ]
      # Options for the `req` tool (`man req`).
      default_bits        = 2048
      distinguished_name  = req_distinguished_name
      string_mask         = utf8only
      
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md          = sha256
      # Extension to add when the -x509 option is used.
      x509_extensions     = v3_ca
      [ req_distinguished_name ]
      countryName				= Country Name (2 letter code)
      countryName_min			= 2
      countryName_max			= 2
      stateOrProvinceName		= State or Province Name (full name)
      localityName			= Locality Name (eg, city)
      0.organizationName		= Organization Name (eg, company)
      organizationalUnitName	= Organizational Unit Name (eg, section)
      commonName			= Common Name (eg, your website's domain name)
      commonName_max			= 64
      emailAddress			= Email Address
      emailAddress_max		= 40
      # Optionally, specify some defaults.
      countryName_default             = GB
      stateOrProvinceName_default     = Hampshire
      localityName_default            = Southampton
      0.organizationName_default      = Cortex Ltd
      organizationalUnitName_default	= Cortex 
      emailAddress_default			= info@cortex.co.uk
      [ v3_ca ]
      # Extensions for a typical CA (`man x509v3_config`).
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid:always,issuer
      basicConstraints = critical, CA:true
      keyUsage = critical, digitalSignature, cRLSign, keyCertSign
      
    2. Save the file as ca.cnf in the directory created for the certificates above.

    3. In the PowerShell window, run the following command:

      openssl req -sha256 -x509 -new -nodes -key cortexCA.key -days 3650 -out cortexCA.pem -config ca.cnf
      
    4. Press Enter for all parameters except the Common Name. For this enter Cortex CA.

  3. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command:

    openssl pkcs12 -export -inkey cortexCA.key -in cortexCA.pem -out cortexCA.pfx
    
  4. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr.

  5. Double click on the cortexCA.pfx file in the certificates folder to import the certificate into the Windows Certificate Store. Perform the following steps:

    1. Select Local Machine then click Next.
    2. Click Next.
    3. Enter the Export Password which the certificate was generated with then click Next.
    4. Select Place all certificates in the following store.
    5. Click Browse….
    6. Select Trusted Root Certification Authorities, click OK then click Next.
    7. Click Finish.

Generate the Certificate

  1. Create a private key for the SSL cert by running the following command:

    openssl genrsa -out cortex.key 2048
    
  2. Generate the SSL certificate request:

    1. Copy the following text into a text editor:

      RANDFILE		= .rnd
      [ ca ]
      default_ca	= CA_default	# The default ca section
      [ CA_default ]
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md        = sha256
      policy            = policy_loose
      [ policy_loose ]
      # Allow the intermediate CA to sign a more diverse range of certificates.
      # See the POLICY FORMAT section of the `ca` man page.
      countryName             = optional
      stateOrProvinceName     = optional
      localityName            = optional
      organizationName        = optional
      organizationalUnitName  = optional
      commonName              = supplied
      emailAddress            = optional
      [ req ]
      # Options for the `req` tool (`man req`).
      default_bits        = 2048
      distinguished_name  = req_distinguished_name
      string_mask         = utf8only
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md          = sha256
      # Extension to add when the -x509 option is used.
      x509_extensions     = v3_req
      req_extensions      = v3_req
      [ req_distinguished_name ]
      countryName			= Country Name (2 letter code)
      countryName_min			= 2
      countryName_max			= 2
      stateOrProvinceName		= State or Province Name (full name)
      localityName			= Locality Name (eg, city)
      0.organizationName		= Organization Name (eg, company)
      organizationalUnitName	= Organizational Unit Name (eg, section)
      commonName			= Common Name (eg, your website's domain name)
      commonName_max			= 64
      emailAddress			= Email Address
      emailAddress_max		= 40
      # Optionally, specify some defaults.
      countryName_default             = GB
      stateOrProvinceName_default     = Hampshire
      localityName_default            = Southampton
      0.organizationName_default      = Cortex Ltd
      organizationalUnitName_default  = Cortex 
      emailAddress_default	       = info@cortex.co.uk
      [ v3_req ]
      basicConstraints = CA:FALSE
      keyUsage = nonRepudiation, digitalSignature, keyEncipherment
      subjectAltName = @alt_names
      [ alt_names ]
      # Specify all DNS and/or IP addresses that clients can use to access the secured resource.
      DNS.1 = MACHINE-NAME 
      DNS.2 = FULLY QUALIFIED MACHINE NAME
      DNS.3 = localhost 
      IP.1 = IP ADDRESS
      IP.2 = 127.0.0.1 
      
    2. Modify the section [alt_names] to include all the required DNS names and IP addresses that clients can use to access the secured resource. Each DNS name or IP address entry must be suffixed with .N where N is the unique index of the DNS name or IP address entry; see below for examples:

      Resource URL Configuration to add
      https://cortex.co.uk/gateway DNS.1 = cortex.co.uk
      https://internal.cortex.co.uk/gateway DNS.2 = internal.cortex.co.uk
      https://10.0.0.0/gateway IP.1 = 10.0.0.0
      https://192.168.1.100/gateway IP.2 = 192.168.1.100
    3. Save the file as san.cnf in the directory created for the certificates above.

    4. In the PowerShell window, run the following command:

      openssl req -new -sha256 -key cortex.key -out cortex.req -extensions v3_req -config san.cnf
      
    5. Press Enter for everything except the Common Name. For this enter Cortex.

    6. Sign the request with a previously generated Root CA by running the following command:

      openssl x509 -req -sha256 -in cortex.req -CA cortexCA.pem -CAkey cortexCA.key -CAcreateserial -out cortex.pem -days 3650 -extensions v3_req -extfile san.cnf
      
    7. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command:

      openssl pkcs12 -export -inkey cortex.key -in cortex.pem -out cortex.pfx
      
    8. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr.

Import the Certificate

  1. Double click on the cortex.pfx file in the certificates folder to get the certificate imported to the Windows Certificate Store. Perform the following steps:
    1. Select Local Machine then click Next.
    2. Click Next.
    3. Enter the Export Password which the certificate was generated with then click Next.
    4. Select Place all certificates in the following store.
    5. Click Browse….
    6. Select Personal, click OK then click Next.
    7. Click Finish.

3.1.1.3.5 - Encrypt Text

Information about encrypting text using the Cortex Encryptor.

Encrypt Text

To encrypt text using the Cortex Encryptor PowerShell module:

  1. Extract the Cortex Innovation 2022.9 - Encryptor.zip file to a folder with the same name.

  2. Open a Windows PowerShell (x64) window as administrator.

  3. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Encryptor folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Encryptor"
    
  4. In the Windows PowerShell (x64) window, run the following command to import the module:

    Import-Module .\Cortex.Encryptor.psd1
    
  5. In the Windows PowerShell (x64) window, run the following command to encrypt text, replacing text to encrypt with the text that you want to encrypt:

    ConvertTo-EncryptedText -Text "text to encrypt"
    

    The command will return the encrypted text, beginning with #_. This step can be repeated for any texts that need to be encrypted.

3.1.1.3.6 - Port Requirements for Application Servers and Load Balancer

Information about the ports opened when installing Cortex Innovation.

Port Requirements for Application Servers and Load Balancer

Cortex Innovation and Microsoft Service Fabric open a range of firewall ports between the servers and specific services. Some of them are opened during installation, others are opened dynamically as needed. These are opened on Windows Firewall. If any other firewall exists between the servers, it will be necessary to configure this selection of rules on it. Most ports may be altered if another program overlaps with them, the description will say if this is not possible.

Cortex Innovation Ports

Name Description Default Port(s) Protocol Direction
Cortex.RabbitMqAmqpPorts The port used by AMQP 0-9-1 and 1.0 clients with TLS. This cannot currently be changed. 5671 TCP Inbound
Cortex.RabbitMqEpmdPorts The port used by epmd, a peer discovery service used by RabbitMQ nodes and CLI tools. This cannot currently be changed. 4369 TCP Inbound
Cortex.RabbitMqErlangDistribut ionClientPorts The ports used by CLI tools (Erlang distribution client ports) for communication with nodes and is allocated from a dynamic range (computed as Erlang dist port + 10000 through dist port + 10010). This cannot currently be changed. 35672-35682 TCP Inbound
Cortex.RabbitMqErlangDistribut ionServerPort The port used for RabbitMQ inter-node and CLI tools communication (Erlang distribution server port) and is allocated from a dynamic range (limited to a single port by default, computed as AMQP port + 20000). This cannot currently be changed. 25672 TCP Inbound
Cortex.RabbitMqManagement ApiPort The port used by the RabbitMQ management plugin. This cannot currently be changed. 15671 TCP Inbound
Cortex.WindowsSmbRemote Registry The ports used by Windows SMB and Remote Registry service. 135, 137, 138, 139, 445 TCP Inbound
Cortex.ServiceFabric.Customer1. ClusterConnectionEndpointPort The port used by the client to connect to the cluster when client APIs are used. 8001 TCP Inbound
Cortex.ServiceFabric.Customer1. ClientConnectionEndpointPort The port where the nodes communicate with each other. 8002 TCP Inbound
Cortex.ServiceFabric.Customer1. ServiceConnectionEndpointPort The port used by the applications and services deployed on a node to communicate with the Service Fabric client on that particular node. 8004 TCP Inbound

Microsoft Service Fabric Firewall Rules (present on all Application Servers, with Domain, Public and Private Profiles)

These rules will all appear in Windows Firewall with names starting with ‘{CustomerName}.{NodeName} WindowsFabric’.

Name in Rule Name in Config Description Default Port(s) Protocol(s) Direction
Application Processes application Ports The ports that are used by the Service Fabric applications. Service Fabric uses these ports whenever new dynamic ports are required. The application port range should be large enough to cater for the dynamic port allocation of the application. Currently at least 400 is recommended. This may change if new services are added. This range should not overlap the Dynamic Ports (ephemeralPorts) range as set in the configuration.

Program: Any
10010-10500 TCP, UDP Inbound, Outbound
BackupRestore Service Process N/A The port used by the Service Fabric process which manages the backup and restore of Application Services.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_\BRS.Code.Current\FabricBRS.exe
Any TCP Inbound, Outbound
CentralSecret Service Process N/A The port used by the Service Fabric process which manages secrets.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_\BRS.Code.Current\FabricCSS.exe
Any TCP Inbound, Outbound
DCA Process N/A The port used by the Service Fabric Diagnostics Collection Agent, which manages Diagnostic data.

Program: %ProgramFiles%\Microsoft Service Fabric\bin\ Fabric\DCA.Code\FabricDCA.exe
Any TCP Outbound
Dynamic Ports ephemeral Ports Override the dynamic ports used by the OS. Service Fabric uses a part of these ports as application ports, and the remaining are available for the OS. It also maps this range to the existing range present in the OS, so for all purposes, you can use the ranges given in the sample JSON files. Make sure that the difference between the start and the end ports is at least 255. You might run into conflicts if this difference is too low, because this range is shared with the OS. To see the configured dynamic port range, run netsh int ipv4 show dynamicport tcp.

Program: Any
10501-20000 TCP, UDP Inbound, Outbound
EventStore Service Process N/A The port used by the Service Fabric EventStore, which maintains events about the state of the Application Services.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\ES.Code.Current\ EventStore.Service.exe
Any TCP Inbound, Outbound
Fabric Gateway Process N/A The port used by the Service Fabric Gateway, which allows REST and management functions to access the Application Services.

Program: %ProgramFiles%\Microsoft Service Fabric\bin\Fabric\ Fabric.Code\FabricGateway.exe
Any TCP Inbound, Outbound
Fabric Process N/A The port used by the main Service Fabric service.

Program: %ProgramFiles%\Microsoft Service Fabric\bin\Fabric\ Fabric.Code\Fabric.exe
Any TCP Inbound, Outbound
FabricUpgrade Service Process N/A The port used by the Service Fabric Upgrade service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\US.Code.Current\FabricUS.exe
Any TCP Inbound, Outbound
FaultAnalysis Service Process N/A The port used by the Service Fabric Fault Analysis service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\FAS.Code.Current\FabricFAS.exe
Any TCP Inbound, Outbound
FileStore Service Process N/A The port used by the Service Fabric File Store service, which manages the application file store and image store.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\FileStoreService.Code.Current\ FileStoreService.exe
Any TCP Inbound, Outbound
GatewayResource Manager Process N/A The port used by the Service Fabric Gateway Resource Manager, which provides APIs to manage the Application Services and other resources.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\GRM.Code.Current\FabricGRM.exe
Any TCP Inbound, Outbound
HTTP App Gateway reverse Proxy Endpoint Port This port cannot be changed at the current time. If it is already in use, please contact Cortex for assistance. The reverse proxy endpoint. For more information, see Service Fabric reverse proxy.

Program: Any
9081 TCP Inbound, Outbound
Http Gateway http Gateway Endpoint Port The port used by Service Fabric Explorer to connect to the cluster. This changes the port used to connect to the Service Fabric management portal as part of the post-install checks.

Program: Any
9080 TCP Inbound, Outbound
Infrastructure Service Process N/A The port used by the Service Fabric Infrastructure Service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\IS.Code.Current\FabricIS.exe
Any TCP Inbound, Outbound
Lease Driver lease Driver Endpoint Port The port used by the cluster lease driver to find out if the nodes are still active.

Program: Any
9002 TCP Inbound, Outbound
ManagedIdentity TokenService Process N/A The port used by the Service Fabric Managed Identity Token Service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\MITS.Code.Current\ ManagedIdentityTokenService.exe
Any TCP Inbound, Outbound
RepairManager Service Process N/A The port used by the Service Fabric Repair Manager Service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\RM.Code.Current\FabricRM.exe
Any TCP Inbound, Outbound
Upgrade Orchestration Service Process N/A The port used by the Service Fabric Upgrade Orchestration service.

Program: %ProgramData%\SF\.\Fabric\work\Applications\ __FabricSystem_App*\UOS.Code.Current\FabricUOS.exe
Any TCP Inbound, Outbound

Cortex Application Service Rules

Each service has an endpoint which is used to communicate with Service Fabric and the RabbitMQ message broker. These are configured in the ServiceManifest.xml file within each package in the ApplicationPackages\Cortex directory of the installation media. These ports cannot be used by any other program. If they do clash with another program, they may be changed but additional configuration changes may be necessary, as described in the description of each port. The Application ports must not lie in the ephemeralPorts range.

Name of Service Description Default Port(s) Protocol(s) Direction Program
API Gateway The port providing an entry into the API Gateway service. This is used by Cortex Gateway to communicate with the Application Services. If this is changed then it will be necessary to use the updated value in the "Service Fabric Api Gateway Endpoint" parameter of SetParameters.xml when configuring Cortex Gateway later in this document. 8722 TCP, UDP Inbound, Outbound Any
Flow Execution The ports providing communication between other services and the stateful Cortex Flow Execution service. These are dynamic ports managed by Service Fabric. Dynamic – Uses the application ports N/A N/A N/A

Cortex Load Balancer Rules

The load balancer server must be able to retrieve traffic via HTTPS. The following firewall ports are opened by the installer (these rules will all appear in Windows Firewall with names starting with {CustomerName}):

Name in Rule Name in Config Default Port(s) Protocol(s) Direction Program
GoBetweenTlsPort loadBalancerTlsPort 443 TCP Inbound Any

3.1.1.3.7 - Rollover CA certificates

Information about updating the certificates on a single or multi-server Cortex platform which uses CA certificates.

Rollover CA certificates

This process MUST be undertaken before certificates expire, otherwise your system will become unusable. If certificates have already expired, contact Cortex Service Portal at the earliest opportunity.

Only platforms which use CA certificates can have their certificates updated using this mechanism. Systems using self-signed certificates must be reinstalled.

This mechanism cannot be used to switch from self-signed to CA certificates; that requires a reinstall.

Application Server

Prerequisites

Certificate Requirements

A new, valid X.509 certificate needs to be obtained to update the certificates.

The certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in a wildcard format, pertaining to the domain of the Application Servers (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.
  • Key Usage extension must have a value of Digital Signature, Key Encipherment (a0).
  • Enhanced Key Usage must include Server Authentication and Client Authentication.

This file should be placed in a known location on the Application Server where the certificate update script will be run. This location will be required when running the update script.

If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject field can also be the FQDN of the load balancer (e.g. CN=machine-name.domain.com).

Configure Update Certificates Script

  1. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, locate the Cortex.Innovation.Update.Certificates.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Update.Certificates.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -ClientCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ClientCertificatePwd "myPassword" `
        -Credential $Credential
            
    
    .\Cortex.Update.Certificates.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -SkipLoadBalancer `
        -Credential $Credential
            
    Name Description
    ServerCertificatePath The local path of a new, valid .PFX certificate file on the server. Environment variables cannot be used.

    The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the Application Services.
    • Allowing Application Services to identify themselves to clients such as Gateway.
    • Preventing unauthorised nodes from joining the single node cluster.
    • Connecting to Service Fabric Explorer from each of the Application Servers.
    ServerCertificatePwd The password for the .PFX certificate file specified in ServerCertificatePath.
    ClientCertificatePath The local path of a .PFX certificate file on the first Application Server in the ApplicationServerIPv4Addresses list. This can be the same certificate as the ServerCertificatePath. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the load balancer and the nodes on the Application Servers.
    ClientCertificatePwd The password for the .PFX certificate file specified in ClientCertificatePath.

    This is only needed if using the Built-In Load Balancer.
    SkipLoadBalancer Updates certificates without updating a load balancer.
    Credential The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.

Test Update Certificates Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Test Cortex.Innovation.Update.Certificates.ps1 by running the following command:

    .\Cortex.Innovation.Update.Certificates.ps1 -WhatIf
    
  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  5. Wait for the command to finish. It will display the output of the certificate update command without making any changes to the system.

  6. Check that there have been no errors in the script; these would appear in red in the console.

    If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them.

    If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

    If this does not work, please contact Cortex Service Portal for further assistance. The WhatIf script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with -WhatIf (e.g. Cortex.Innovation.Install.Config-WhatIf.json). This file can be provided when obtaining support.

Run Update Certificates Script

  1. Update the certificates for the Application Services and the required infrastructure by running the following command (Tee-Object will write output to both the PowerShell console and a log file, the FilePath value can be changed if required):

    .\Cortex.Innovation.Update.Certificates.ps1 | Tee-Object -FilePath "cortex-app-certificate-update-log.txt"
    
  2. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  3. Wait for the script to finish running. This should take approximately 10 minutes.

  4. Check that there have been no errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation.

    If the errors do not give any instructions on how to rectify, see Troubleshooting During Installation for further information; if this does not help then please contact Cortex Service Portal for assistance.

Check Application Services

  1. Log on to the server.

  2. Import the certificate, used in the ServerCertificatePath parameter of the Configure Update Certificates Script section, to your Current User certificate store. This can be achieved by double clicking on the certificate .PFX file and following the wizard.

  3. Open a web browser.

  4. Navigate to https://server.domain.com:9080/Explorer, where server.domain.com is the fully qualified domain name of the server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    The screen should resemble that in the following figure:

    Healthy Service Fabric Explorer Cluster

    The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on.

    If there is still a warning that the certificate is close to expiring, wait a few hours and refresh the page and it should go away. It can take some time for the certificate to rollover.

Web Application Server

If the Web Applications also use an expiring certificate, it will also need to be updated:

Import the Certificate

If using a single server and using the same certificates for both the Application Services and Web Applications, a new certificate will already be installed. Otherwise, follow the following instructions to import the new certificate for use with the Web Applications:

  1. Put the new, valid certificate in .pfx format on the Web Application Server.
  2. Double click on the certificate file to open the install certificate wizard.
  3. Select Local Machine then click Next.
  4. Click Next.
  5. Enter the Export Password which the certificate was generated with then click Next.
  6. Select Place all certificates in the following store.
  7. Click Browse….
  8. Select Personal, click OK then click Next.
  9. Click Finish.

Apply the Certificate

  1. Open Internet Information Services (IIS) Manager.
  2. In the left-hand pane of Internet Information Service (IIS) Manager, expand the server node.
  3. Right-click on the Site node (usually Cortex) which contains the Debugger and Gateway.
  4. Click Edit Bindings...
  5. Click on the https binding and click Edit....
  6. Click the SSL Certificate Select... button and select the new certificate from the table. Click OK to close the dialog.
  7. Click OK to close Edit Bindings dialog.
  8. Click Close to close the Bindings dialog.
  9. Open Gateway in a browser. Click the padlock icon next to the URL. The certificate displayed should be the updated one.

3.1.1.3.8 - SSL Best Practices

Information about the recommended security settings for Innovation servers.

SSL Best Practices

A collection of registry settings can be applied during installation to guarantee your server is only using the recommended encryption algorithms and TLS protocols:

Type Name Enabled
Ciphers AES 128/128
AES 256/256
Triple DES 168
DES 56/56
NULL
RC2 128/128
RC2 40/128
RC2 56/128
RC4 128/128
RC4 40/128
RC4 56/128
RC4 64/128
Hashes MD5
SHA
SHA256
SHA384
SHA512
KeyExchangeAlgorithms Diffie-Hellman
ECDH
PKCS
Protocols Multi-Protocol Unified Hello
PCT 1.0
SSL 2.0
SSL 3.0
TLS 1.0
TLS 1.1
TLS 1.2
Cipher Suites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA25
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
TLS_DHE_DSS_WITH_AES_256_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_RC4_128_MD5
TLS_RSA_WITH_NULL_SHA256
TLS_RSA_WITH_NULL_SHA
TLS_PSK_WITH_AES_256_GCM_SHA384
TLS_PSK_WITH_AES_128_GCM_SHA256
TLS_PSK_WITH_AES_256_CBC_SHA384
TLS_PSK_WITH_AES_128_CBC_SHA256
TLS_PSK_WITH_NULL_SHA384
TLS_PSK_WITH_NULL_SHA256

3.1.2 - Add Innovation to a 7.2 Installation

Information about adding Cortex Innovation to an existing Cortex 7.2 platform.

Cortex Innovation can be deployed on-premise across multiple servers to provide improved scale and high availability (HA), or to a single server if scale and HA aren’t required.

3.1.2.1 - Multiple Server - With HA (Recommended)

Information about adding Cortex Innovation to Cortex 7.2 across multiple on-premise servers with high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions.

Multiple server installations with HA are recommended for the following scenarios:

  • Production installations that are required to scale and support HA

3.1.2.1.1 - Architecture

Information about the recommended platform architecture, including component descriptions.

Architecture

Components

Component Purpose Required/Optional Server Role
Cortex Gateway Web portal that hosts applications for creating automation solutions and managing their full life-cycle, including design, development, testing, deployment, monitoring, maintenance and ultimately end-of-life. Required Web Application Server
Cortex Studio Application hosted in Cortex Gateway that provides the graphical, low-code environment for developing, testing, versioning, publishing and managing the full life-cycle of automation solutions. Required Web Application Server
Cortex Flow Debugger Service Web application that allows flows to be debugged and executed. Used by Cortex Studio to debug flows and provide block information. Required Web Application Server
Cortex API Gateway Service Application Service that routes client requests to the correct distributed Cortex services. Required Application Server
Cortex Flow Execution Service Application Service that executes automation flows. Required Application Server
Cortex Block Packages A set of files which contain the blocks that users can use to build flows. Used by the Cortex Flow Debugger Service and the Cortex Flow Execution Service. Required Web Application Server, Application Server
Cortex Gateway Databases A set of databases created automatically by Gateway which are used for storing data related to user roles, flows, etc. Hopefully, we can remove the need for Gateway Databases in the next release. Required
(End of life)
Web Application Server
SQL Server Express or SQL Server Standard Required by Cortex Gateway for creating and storing the Gateway Databases. Hopefully, we can remove the need for SQL Server in the next release. Required
(End of life)
Web Application Server
Microsoft Service Fabric Distributed systems platform that hosts the Cortex services where automation solutions are deployed to; provides scalable, reliable and manageable enterprise-grade High Availability (HA) using clustering. Required Application Server
Microsoft Service Fabric Explorer Web portal for monitoring and managing the Service Fabric instance that automation solutions are deployed to. Required Application Server
Particular NServiceBus Messaging platform enabling scalable, reliable and flexible asynchronous messaging between distributed Cortex services. Required Application Server
Pivotal RabbitMQ Message broker used by the NServiceBus messaging platform to transport messages asynchronously between distributed Cortex services using publish/subscribe mechanism. Required Application Server
Erlang OTP Erlang run-time required by the RabbitMQ message broker. Required Application Server
gobetween L4 load balancer and reverse proxy used to load balance requests between clustered instances of Cortex services. Required Load Balancer
NSSM Windows Service Manager that hosts the gobetween load balancer application as a Windows Service. Required Load Balancer

Possible Architectures

Cortex Innovation and v7.2 can run side-by-side, allowing flows to be built and run for both of them from the same Gateway instance. They each require a different set of back-end components to be installed. Innovation can be added to a v7.2 installation by using the existing hardware containing v7.2 components, using new hardware or a combination of the two. The only components shared by both Innovation and v7.2 are Gateway and its databases.

The installation process is the same, regardless of which architecture is used; Recommended, Minimum or Alternative. The only difference is the Hardware Requirements, which will be greater for existing machines as they need more resources to run more components.

The recommended architecture for adding Innovation to a v7.2 Dual Site, Dual Server system requires 8 servers in total; the 4 existing servers, plus 4 new servers:

  • 2x Existing Application Servers for v7.2, one of these will also act as the Web Application Server for Innovation. For Innovation, the existing Gateway will be upgraded and a new Flow Debugger Service will be added.
  • 2x Existing Database Servers, used for v7.2 and Gateway databases.
  • 1x New Load Balancer Server for Innovation.
  • 3x New Application Servers for Innovation.

8 Server, Recommended Architecture Diagram

.

Minimum Architecture

The minimum architecture requires only the 4 existing servers:

  • 2x Application Servers for v7.2, each of these will also host one of the three Application Servers for Innovation.
  • 1x Database Server for v7.2, which will also host the remaining Application Server for Innovation.
  • 1x Database Server for v7.2, which will also host the Load Balancer for Innovation.

4 Server, Minimum Architecture Diagram

.

Alternative Architectures

Alternative architectures are possible; any of the Innovation server roles may be installed on any of the existing or new servers provided that the hardware is capable of running everything according to the Hardware Requirements for Alternative Architectures. For example, if the database servers cannot have anything else installed on them, new servers may be used for the load balancer and the third Innovation Application Server. Additionally, an existing, alternative load balancer may be used instead of the bundled one. The only caveat is that the load balancer must not be installed on the same machine as an Innovation Application Server as it cannot be used to send traffic to itself.

Next Steps?

  1. Prerequisites

3.1.2.1.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for each server role (as described in Architecture) are laid out in this guide. These must be considered before undertaking installation.

Hardware Requirements

Hardware requirements differ for each server role depending on whether it is being installed on new hardware or hardware which already contains v7.2 components. The minimum requirements for existing hardware will be greater than those for new hardware. The requirements for using the Recommended Architecture can be found here. Requirements for using the Minimum Architecture can be found here. This table is also provided to help calculate requirements for Alternative Architectures.

Use these hardware requirements if using the Recommended Architecture.

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
New Innovation Load Balancer 11 4+ Recommended
Minimum
8+ Recommended
Minimum
50+ Recommended
30 Minimum
5+ free on installation drive
New Innovation Application Server Bronze availability2
Silver availability
Gold availability
Platinum availability
4+ Recommended
Minimum
16+ Recommended
Minimum
75+ Recommended
60 Minimum
40+ free on %ProgramData% drive
Existing V7.2 Application Server with Gateway
+ Upgrade to Innovation Web Application Server
1 4+ Recommended
Minimum
8+ Recommended
Minimum
75+ Recommended
50 Minimum
30+ free on installation drive

Minimum Architecture

Use these hardware requirements if using the Minimum Architecture and installing on existing v7.2 hardware.

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
Existing V7.2 Database Server
+ Innovation Load Balancer
11 4+ Recommended
Minimum
8+ Recommended
Minimum
300+ Recommended
70 Minimum
5+ free on installation drive
Existing V7.2 Database Server
+ Innovation Application Server
1 4+ Recommended
Minimum
16+ Recommended
12 Minimum
300+ Recommended
100 Minimum
40+ free on %ProgramData% drive
Existing V7.2 Application Server
+ Innovation Application Server
1 4+ Recommended
Minimum
16+ Recommended
12 Minimum
120+ Recommended
100 Minimum
40+ free on %ProgramData% drive
Existing V7.2 Application Server with Gateway
+ Innovation Application Server
+ Upgrade to Innovation Web Application Server
1 4+ Recommended
Minimum
16+ Recommended
12 Minimum
120+ Recommended
100 Minimum
30+ free on installation drive
40+ free on %ProgramData% drive

Alternative Architectures

This table displays the additional resources required when adding an Innovation Server Role to an existing server using Alternative Architectures. It can be used to calculate how many additional resources are needed to install Innovation by adding the numbers in the table to fully utilised resource usage on a given server.

Server Role Minimum Additional CPU Cores (> 2GHz) Minimum Additional RAM (GB) Minimum Additional Disk (GB)
Load Balancer 2 2 10 free on installation drive
Application Server 2 8 40 free on %ProgramData% drive
Web Application Server 2 4 30 free on installation drive

Software Requirements

Server Role Windows Server3 SQL Server4 .Net PowerShell5 IIS6 Other Software
Load Balancer 2019 (x64) Recommended
2016 (x64)
Framework 4.7.1 5.1
Application Server 2019 (x64) Recommended
2016 (x64)
Framework 4.7.1 5.1
Web Application Server 2019 (x64) Recommended
2016 (x64)
2019
2016
2016 Express
Framework 4.7.1 5.1 10.0.177637
10.0.143938
URL Rewrite Module 2.1
Microsoft Web Deploy 3.0 or later
Visual C++ Redistributable 2013 (x64)

Domain Requirements

All servers must be on the same domain and cannot be domain controllers.

DNS Requirements

The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for all of your servers (Web, Application and Load Balancer).

Licensing Requirements

A valid Cortex licence file and Cortex Innovation with v7.2 feature identifier must be procured from Cortex. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the Web Application server and it should contain fingerprints for the Web Application Server and each Application Server.

To get a licence file and feature identifier take the following steps:

  1. Copy the following template to a text file:

    Web Application Server
    MachineID: 
    Fingerprint: 
    
    Application Server 1
    MachineID: 
    Fingerprint: 
    
    Application Server 2
    MachineID: 
    Fingerprint: 
    
    Application Server 3
    MachineID: 
    Fingerprint: 
    
    Please also include a suitable Cortex Innovation with v7.2 feature identifier.
    
  2. Extract Cortex Innovation 2022.9 - Licence Fingerprint Generator.zip.

  3. From that folder, copy Cortex.Licensing.FingerprintGeneration.exe to the Web Application server.

  4. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

    MachineID: WEBAPP-SERVER
    Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
    
  5. Copy the output (machine identifier and fingerprint) to the Web Application Server section of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server.

  6. For each Application Server take the following steps:

    1. Copy Cortex.Licensing.FingerprintGeneration.exe to the Application server.

    2. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

      MachineID: APP-SERVER1
      Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
      
    3. Copy the output (machine identifier and fingerprint) to one of the Application Server sections of the text file created in the initial step. Note that the machine identifier can be changed to any string, provided that it is different for each server.

  7. Request a licence and feature identifier by raising a case in the Cortex Service Portal, including the contents of the text file containing all of the fingerprint and machine information in the body of the case.

  8. When the licence and feature identifier have arrived, copy the file Cortex.lic to %ProgramData%\Cortex\Licences on the Web Application Server, creating the Cortex and Licences folders if they don’t exist. Save the feature identifier for use when Upgrading Gateway.

Web Browser Requirements

Gateway supports the latest versions of the following browsers:

  • Chrome
  • Edge
  • Firefox

Additional Load Balancer Server Requirements

Filesystem Requirements

If using the included gobetween load balancer, Network Discovery and File Sharing must be enabled on the Load Balancer Server:

  1. Open File Explorer.
  2. Click Network on the left.
  3. A banner similar to the following will appear if Network Discovery and File Sharing is turned off:

    Network and File Discovery Disabled

  4. Click the banner.
  5. Click Turn on network discovery and file sharing:

    Enable Network and File Discovery

Alternative Load Balancer Requirements

Innovation has a gobetween load balancer included that isn’t highly available; It is possible to use an alternative. The requirements for installing an alternative load balancer are as follows:

  • Must support a round robin (or similar) method of load balancing to specified ports on 3 nodes.
  • Must be able to health check each node by running a predefined batch script (ApiGatewayTypeHealthcheck.bat, which resides in the gobetween folder of the Cortex Innovation 2022.9 - App Server Install Scripts) that returns 1 for healthy and 0 for unhealthy.
  • Must be able to access each of the Application Servers via HTTPS.
  • Ideally it should be highly available to avoid a single point of failure in the system.

Additional Application Server Requirements

Filesystem Requirements

All Application Servers must use an NTFS filesystem.

Network Discovery and File Sharing should be enabled on each Application Server:

  1. Open File Explorer.
  2. Click Network on the left.
  3. A banner similar to the following will appear if Network Discovery and File Sharing is turned off:

    Network and File Discovery Disabled

  4. Click the banner.
  5. Click Turn on network discovery and file sharing:

    Enable Network and File Discovery

Service Requirements

The following Windows Services must be running on all Application Servers:

  • Remote Registry
  • Windows Event Log
  • Performance Logs & Alerts

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on all Application Servers and Load Balancer Server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the HA platform that Cortex Innovation is built upon.

Antivirus Exclusions

It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on each Application Server to reduce antivirus processing on Service Fabric artefacts:

Folder Exclusions:

  • %ProgramFiles%\Microsoft Service Fabric
  • %ProgramData%\SF
  • %ProgramData%\SF\Logs

Process Exclusions:

  • Fabric.exe
  • FabricHost.exe
  • FabricInstallerService.exe
  • FabricSetup.exe
  • FabricDeployer.exe
  • ImageBuilder.exe
  • FabricGateway.exe
  • FabricDCA.exe
  • FabricFAS.exe
  • FabricUOS.exe
  • FabricRM.exe
  • FileStoreService.exe

A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually.

If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist.

Port Requirements

Cortex Innovation and Microsoft Service Fabric require a range of firewall ports to be opened between the servers and specific services.

If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in Port Requirements to open the correct ports.

The Cortex.Innovation.Test.PortUsage.ps1 script is provided during installation to test the ports on each Application Server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible.

Certificate Requirements

An X.509 SSL wildcard certificate should be used to:

  • Secure communication between the load balancer and the nodes on the Application Servers.
  • Secure communication between the Application Services.
  • Allow Application Services to identify themselves to clients such as Gateway.
  • Prevent unauthorised nodes from joining the HA cluster.
  • Connect to Service Fabric Explorer from each of the Application Servers.

The certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in a wildcard format, pertaining to the domain of the Application Servers (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.
  • Key Usage extension must have a value of Digital Signature, Key Encipherment (a0).
  • Enhanced Key Usage must include Server Authentication and Client Authentication.

This file should be placed in a known location on the Application Server where the installation scripts will be run. This location will be required when running the installation script.

If required, a separate X.509 SSL certificate can be obtained to be used by the load balancer to communicate with the Application Services. It must meet all of the other requirements laid out above, except the subject field can also be the FQDN of the load balancer (e.g. CN=machine-name.domain.com).

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the Application Servers, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the Application Servers.

Additional Web Application Server Requirements

Security Requirements

Installation User

Domain users must be available to run the Application Pools for Gateway and Flow Debugger Service. These users must be given Log on as a service and Log on as a batch job permissions otherwise the Application Pools will not be able to run. Information about how to do this will be given during installation.

For Flow Debugger Service, the NETWORK SERVICE user can also be used.

Domain Requirements

For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported.

Supported versions of Active Directory are listed below:

Version Verified? Supported From Supported Until
Windows Server 2003 Cortex v2022.9 To be evaluated
Windows Server 2003 R2 Cortex v2022.9 To be evaluated
Windows Server 2008 Cortex v2022.9 To be evaluated
Windows Server 2008 R2 Cortex v2022.9 To be evaluated
Windows Server 2012 Cortex v2022.9 To be evaluated
Windows Server 2012 R2 Cortex v2022.9 To be evaluated
Windows Server 2016 Cortex v2022.9 To be evaluated
Windows Server 2019 Cortex v2022.9 To be evaluated
Windows Server 2022 Cortex v2022.9 To be evaluated

Certificate Requirements

Both Gateway and the Flow Debugger Service require an X.509 SSL certificate to be installed on the Web Application Server. The certificate must have the following properties:

  • Enhanced Key Usage: Server Authentication and Client Authentication
  • Subject Alternative Names (SAN): At minimum the FQDN of the Server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1

If the user tries to navigate to an address not in the SAN list, then they will receive a certificate error.

Wildcard certificates and self-signed certificates can also be used. However, self-signed certificates are not recommended for production instances. Details on how to create a self-signed certificate can be found at Create Self-Signed Certificates.

The certificate may be the same one used for the Application Server installation.

More information about importing the certificate is given during installation.

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the Web Application Server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2. And disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the Web Application Server.

Next Steps?

Application Servers and Load Balancer server are installed in the same way regardless of whether new or existing hardware is being used:

  1. Install Application Servers and Load Balancer

  1. A software-based load balancer called gobetween is provided with the platform. This must be installed on its own server as it doesn’t support routing traffic to itself. It also doesn’t currently support HA, but it may be possible to use multiple gobetween load balancers with Anycast network addressing and routing to provide high availability, as described in https://en.wikipedia.org/wiki/Anycast; however, this has not been verified yet. It is possible to use an alternative load balancer to the one provided. ↩︎ ↩︎

  2. Application Servers support HA via clustering. A cluster must consist of a minimum of 3 nodes, and the number of nodes must be an odd number to ensure a quorum. Currently only the Bronze availability (3 nodes) is supported. Silver, Gold and Platinum support will be added in future. ↩︎

  3. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

  4. SQL Server Express, Standard and Enterprise are supported. Other databases are not supported. Note that Transparent Data Encryption is not supported on SQL Server Express. ↩︎

  5. PowerShell 5.1 ships with Windows Server 2016 and 2019. ↩︎

  6. IIS is supported; other web servers, including IIS Express are not supported. ↩︎

  7. Ships as a windows role within Windows Server 2019. ↩︎

  8. Ships as a windows role within Windows Server 2016. ↩︎

3.1.2.1.3 - Install Application Servers and Load Balancer

Information about installing the Application Servers and Load Balancer Server.

Install Application Servers and Load Balancer

This guide describes how to install the Application Servers and Load Balancer Server. Please ensure that Prerequisites for adding Innovation to v7.2 have been read before starting this installation.

Make Installation Artefacts Available

  1. Choose one of the Application Servers to be used for installation, and copy the following artefacts to a folder on it (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - App Services.zip
    • Cortex Innovation 2022.9 - App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - App Server Install Scripts.zip file to a folder with the same name.

Install Microsoft .NET Framework 4.7.1

Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.1 to be installed on each Application Server.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

These are non-compulsory security measures, recommended to be applied to Application Servers and the Load Balancer Server, in order to prevent potential attacks that exploit known industry security vulnerabilities.

Applying these measures may impact other applications running on your servers. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes.

A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at SSL Best Practices.

The settings can be applied by running a script. Be aware that each server will be restarted when the script is run. Apply the settings by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers and the LoadBalancerServer value to contain the NETBIOS names or fully qualified domain name of the Load Balancer Server (remove the LoadBalancerServer parameter if using an alternative load balancer):

    .\Cortex.Innovation.Install.Multiple.SSLBestPractices.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3") -LoadBalancerServer "lb-server"
    
  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

    If -Override 0 has been specified no further steps need to be taken and you can move on to the next section when the servers have restarted.

  5. To use all the recommended settings click Apply all to the each Apply Cortex recommended security best practices prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying. This will need to be done for each server.

  6. Restart each machine when the script asks. The current machine will be restarted last, the PowerShell script will close at this time.

Add Antivirus Exclusions

  1. If Windows Defender is not running on the Application Servers, ensure that the Antivirus Exclusions have been added to the running antivirus software on each of the Application Servers and continue to the next section, otherwise follow these steps:
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers:

      .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK.

    5. A message will indicate that the script has completed successfully.

Check Port Usage

  1. To check all necessary ports are free, follow these steps.
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Test.PortUsage.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS names or fully qualified domain names of the Application Servers:

      .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1", "app-server2", "app-server3")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all Application Servers and press OK.

    5. If all ports are free, the script will report the following for each Application Server:

      All ports required by Cortex Innovation are free

      If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the Cortex.Innovation.Install.Config.json configuration file, in the Cortex Innovation 2022.9 - App Server Install Scripts folder, to use different ports. This will be used later during installation.

      The Cortex.Innovation.Test.PortUsage.ps1 script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, locate the Cortex.Innovation.Install.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -LoadBalancerServerIPv4Address "192.168.1.4" `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -ClientCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ClientCertificatePwd "myPassword" `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -LoadBalancerServerIPv4Address "192.168.1.4" `
        -UseSelfSignedCertificates `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -ClientCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ClientCertificatePwd "myPassword" `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1", "192.168.1.2", "192.168.1.3") `
        -UseSelfSignedCertificates `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-ha-install-log.txt"
            
    Name Description
    AppServicesPath Configure this value with the location of the Application Services zip file on the Application Server used for installation.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the Application Server used for installation.
    ApiGatewayBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when upgrading Gateway.
    ApiGatewayBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when upgrading Gateway.
    CustomerName A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer.
    ApplicationServerIPv4Addresses The IPv4 addresses of the Application Servers. The first of these must be the Application Server used for installation.
    LoadBalancerServerIPv4Address The IPv4 address of the Load Balancer Server. This is only needed if using the built-in load balancer.
    ServerCertificatePath The local path of a .PFX certificate file on the first Application Server in the ApplicationServerIPv4Addresses list. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended). The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the Application Services.
    • Allowing Application Services to identify themselves to clients such as Gateway.
    • Preventing unauthorised nodes from joining the HA cluster.
    • Connecting to Service Fabric Explorer from each of the Application Servers.
    ServerCertificatePwd The password for the .PFX certificate file specified in ServerCertificatePath.

    This is only needed if installing with CA Certificates (Recommended).
    ClientCertificatePath The local path of a .PFX certificate file on the first Application Server in the ApplicationServerIPv4Addresses list. This can be the same certificate as the ServerCertificatePath. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer. The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the load balancer and the nodes on the Application Servers.
    ClientCertificatePwd The password for the .PFX certificate file specified in ClientCertificatePath.

    This is only needed if installing with CA Certificates (Recommended) and using the Built-In Load Balancer.
    UseSelfSignedCertificates Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    SkipLoadBalancer Installs Application Services and required infrastructure without installing a load balancer. Use when using an alternative load balancer or no load balancer.
    Credential The credentials of the user which will be used to perform remote operations on the Application Servers. It must be a domain user that is a member of the local Administrators group on all servers.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.

    The ApiGatewayBasicAuthUserName and ApiGatewayBasicAuthPwd will be needed later, when upgrading Gateway.

  3. Save and close Cortex.Innovation.Install.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1 -WhatIf
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -WhatIf -AcceptEULA
    
  5. Run the PowerShell command to test the installation script.

  6. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

  7. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ.

  8. Wait for the command to finish. It will display the output of the installation command without making any changes to the system, to ensure things like communication between the servers are working.

  9. Check that there have been no errors in the script; these would appear in red in the console.

    If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them.

    If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

    If this does not work, please contact Cortex Service Portal for further assistance. The WhatIf script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with -WhatIf (e.g. Cortex.Innovation.Install.Config-WhatIf.json). This file can be provided when obtaining support.

Run Installation Script

  1. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1
    
  2. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  3. Run the PowerShell command to install HA Services and the required infrastructure.

  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.

  5. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from Cortex Service Portal. Press OK.

  6. Wait for the script to finish running. This should take approximately 10 minutes.

  7. Check that there have been no errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation.

    In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command:

    .\Cortex.Innovation.Uninstall.ps1
    

    If the errors do not give any instructions on how to rectify, see Troubleshooting During Installation for further information; if this does not help then please contact Cortex Service Portal for assistance.

Check Application Services

  1. Log on to one of the Application Servers.

  2. Import the client certificate, used in the ClientCertificatePath parameter of the Configure Installation Script section, to your Current User certificate store. This can be achieved by double clicking on the client certificate .PFX file and following the wizard.

    If using self-signed certificates, the certificate can be retrieved by using the Manage Computer Certificates tool in Windows to export the CortexServerCertificate from the Personal store and then importing it to the Current User store by double-clicking on it and following the wizard.

  3. Open a web browser.

  4. Navigate to https://app-server.domain.com:9080/Explorer, where app-server.domain.com is the fully qualified domain name of any Application Server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    The screen should resemble that in the following figure:

    Healthy Service Fabric Explorer Cluster

    The status circles should be entirely green - this indicates that all nodes, services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system.

    After expanding the application, clicking on any of the services should display a green circle and Status = Active:

    Healthy Service Fabric Explorer Service

    After expanding either of the services, clicking on any of the instances/partitions should display a green circle and Status = Ready:

    Healthy Service Fabric Explorer Instance

    Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and Status = Up:

    Healthy Service Fabric Explorer Node

    If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section.

    If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong.

    If no useful message can be seen here, the service log files may contain more information. These can be found on each Application Server at:

    • %ProgramData%/Cortex/Cortex API Gateway Service
    • %ProgramData%/Cortex/Cortex Flow Execution Service

    If no solution can be found, please contact Cortex Service Portal for further assistance.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Upgrade v7.2 Gateway to Include Innovation

3.1.2.1.4 - Upgrade v7.2 Gateway to Include Innovation

Information about upgrading v7.2 Gateway with Innovation functionality.

Upgrade v7.2 Gateway to Include Innovation

This guide describes how to upgrade Gateway on v7.2 to include Innovation. Please ensure that Install Application Servers and Load Balancer has been completed before starting this installation. These steps assume that the v7.2 version of Gateway and its prerequisites have already been installed.

The steps to add Innovation functionality to v7.2 are:

  1. Install Flow Debugger Service
  2. Upgrade Gateway

Make Installation Artefacts Available

  1. We recommend that the Flow Debugger Service and Gateway are installed on the same Web Application Server. Copy the following artefacts to a folder on the machine (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - Gateway.zip
    • Cortex Innovation 2022.9 - Flow Debugger Service.zip
    • Cortex Innovation 2022.9 - Web App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - Web App Server Install Scripts.zip zip file to a folder with the same name.

Install Prerequisites

Licensing

Ensure that a valid Cortex licence file named Cortex.lic exists on the Web Application server, in the location %ProgramData%\Cortex\Licences. If it does not, follow the instructions located at Licensing Requirements.

Install Flow Debugger Service

Get Application Pool User

A domain user account is required for the Flow Debugger Service web application pool and must be created prior to performing the installation. In line with best practices, this account should not be used for any purposes other than those specified for the Flow Debugger Service. Alternatively, the NETWORK SERVICE user may also be used.

This user must currently have access to the default NuGet directory, in order to load block packages correctly. To add permissions for the user take the following steps:

  1. Navigate to %SystemRoot%\System32\config\systemprofile\AppData\Roaming\ and create a new folder named NuGet if one does not exist.
  2. Right-click on the NuGet folder and click Properties.
  3. In the dialog, click the Security tab.
  4. Click the Edit... button.
  5. Click the Add... button.
  6. Enter the username of the application pool user and click OK.
  7. In the Permissions section at the bottom, check Full control
  8. Click OK.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.FlowDebuggerService.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -UseSelfSignedCertificates `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    Name Description
    FlowDebuggerServicePath Configure this value with the location of the Flow Debugger Service zip file on the Web Application Server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the Web Application Server.
    FlowDebuggerBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when upgrading Gateway.
    FlowDebuggerBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when upgrading Gateway.
    UseSelfSignedCertificates Enables Flow Debugger Service to communicate with Gateway using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    Credential The credentials of the user that will be used to run the Debugger application pool in IIS.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.FlowDebuggerService.ps1.

Run Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.FlowDebuggerService.ps1
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  5. Run the PowerShell command to install the Flow Debugger Service.

  6. A credentials prompt will appear. Enter the credentials of the user that should run the Debugger application pool in IIS. If using the NETWORK SERVICE user, enter any user as the username and leave the password blank; the NETWORK SERVICE user will need to be selected in the final step.

  7. Wait for the script to finish running. This should take approximately 2 minutes.

  8. An error may have appeared saying:

    The Windows Process Activation Service service is not started.
    

    This can be ignored.

  9. Check that there have been no other errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation.

    If the errors do not give any instructions on how to rectify, please contact Cortex Service Portal for further assistance.

  10. If using NETWORK SERVICE for the application pool user:

    1. Open Internet Information Services (IIS) Manager.
    2. On the left, expand the server node.
    3. Click Application Pools.
    4. Right-click on the Debugger application pool and select Advanced Settings....
    5. In the Advanced Settings dialog, click on Identity and then click the ellipses (...).
    6. In the Application Pool Identity dialog, select Built-in account, then select NetworkService from the drop-down, then click OK.
    7. Right-click on the Debugger application pool and click Recycle....

Upgrade Gateway

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.Gateway.ps1 script and open it with a text editor.

  2. Configure the script according to the details given below:

    .\Cortex.Install.Gateway.ps1 `
    -GatewayPackagePath "C:\Install\Cortex Innovation 2022.9 - Gateway.zip" `
    -GatewayApplicationIISPath "Cortex\gateway" `
    -FeatureFlags "InnovationId" `
    -ServiceFabricApiGatewayEndpoint "https://server.domain.com/" `
    -ServiceFabricUsingSelfSignedCertificates $false `
    -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" `
    -ServiceFabricApiGatewayBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerEndpoint "https://server.domain.com/debugger/api/" `
    -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" `
    -DotNetFlowDebuggerBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerUsingSelfSignedCertificates $false `
    -Test:$Test `
    -AcceptEULA:$AcceptEula `
    *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt"
    
    Name Description
    GatewayPackagePath Configure this value with the location of the Cortex Innovation 2022.9 - Gateway.zip file on the installation server.
    GatewayApplicationIISPath Change to the correct Site Name/Application if either was modified from the defaults (Cortex/gateway) when creating the website or application.
    FeatureFlags Replace InnovationId with the Cortex Innovation feature identifier, which should have been provided by Cortex when fulfilling the Licensing Requirements, if it wasn’t it should be requested using Cortex Service Portal.

    This will overwrite the FeatureFlags value in the Gateway web.config.
    ServiceFabricApiGatewayEndpoint Replace server.domain.com with the fully qualified domain name of the Load Balancer Server. The port should be specified if it is not the default HTTPS port (443), and there must be a trailing slash, e.g. https://server.domain.com/ or https://server.domain.com:8722/.

    This will overwrite the ServiceFabricApiGatewayEndpoint value in the Gateway web.config.
    ServiceFabricUsingSelfSignedCertificates Configure the value as $false if you used valid CA certificates when installing the Application Servers, $true if you used self-signed certificates.

    This will overwrite the ServiceFabricUsingSelfSignedCertificates value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthUsername This must be changed if you used a non-default ApiGatewayBasicAuthUserName when installing the Application Servers; if so, this value must be configured to the one used.

    This will overwrite the ServiceFabricApiGatewayBasicAuthUsername value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthPassword This must be changed if you used a non-default ApiGatewayBasicAuthPassword when installing the Application Servers; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will overwrite the ServiceFabricApiGatewayBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerEndpoint Replace server.domain.com with the fully qualified domain name of the Web Application Server.

    This will overwrite the DotNetFlowDebuggerEndpoint value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthUsername This must be changed if you used a non-default FlowDebuggerBasicAuthUserName when installing the Flow Debugger Service; if so, this value must be configured to the one used.

    This will overwrite the DotNetFlowDebuggerBasicAuthUsername value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthPassword This must be changed if you used a non-default FlowDebuggerBasicAuthPassword when installing the Flow Debugger Service; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will overwrite the DotNetFlowDebuggerBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerUsingSelfSignedCertificates Configure the value as $false if you are using valid CA certificates to secure the site containing Gateway and Flow Debugger Service, $true if using self-signed certificates.

    This will overwrite the DotNetFlowDebuggerUsingSelfSignedCertificates value in the Gateway web.config.
    Test This does not need to be changed, it will be set at a later stage.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.Gateway.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1 -Test
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -Test -AcceptEULA
    
  5. Run the PowerShell command to test the configuration. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

Run Installation Script

  1. Ensure the Gateway application pool is stopped:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Stop.
  2. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1
    
  3. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  4. Run the PowerShell command to install Gateway. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

  5. Start the Gateway application pool:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Start.
  6. Once the application pool has been started, the site will be available on <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

Next Steps?

  1. Try it out

3.1.2.1.5 - Try it out

Information about trying out Cortex Innovation for the first time.

Try it out

This guide describes how to try out a new Innovation installation to make sure it is working.

Test Debugging Flows

Test the platform by creating a new flow and executing it using the following steps:

  1. Click on the Flows charm, then the + button and click Group to open a dialog.
  2. Enter a name for the group, configure the Permission Groups and click OK to create the group.
  3. Click on the group to open it (refresh the page if it does not appear).
  4. Inside the group, click the + button again and click on Flow(Innovation) to open a dialog. If the menu item is not present, it means that the FeatureFlags in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway. See Troubleshooting for more information.
  5. Enter a name for the flow, configure the Permission Groups and click OK to create the flow.
  6. The flow should be displayed with a start flow block and end flow block. A list of block palettes should be displayed down the left hand side:

    New Flow - Number of palettes may differ

    If the blocks in the flow do not display or the palettes are not visible, see Troubleshooting for more information.
  7. Add a Set Variable block and connect it between the start and end blocks.
  8. Click the Set Variable block to open the Property Editor.
  9. Set the Value property to the expression DateTimeOffset.Now.
  10. Type Result into the Variable property and click Create Result.
  11. In the Variable Editor, set Is Output Variable? to true for the new Result variable.
  12. Set a breakpoint on the end block and start the flow. An execution token should appear, the Result variable should show the current time. If the token does not appear, try refreshing the page.
  13. Continue or stop the execution.
  14. Commit the flow.

Test Publishing Production Flows

  1. Log in to Gateway with a user that has the Admin role.
  2. Click on the Settings charm, then Packages.
  3. Click Add Package Definition. Enter a package name and select the new flow to add to the package. Click Save to save the new package.
  4. Click Publish. A success message should appear. If it doesn’t it means that either one or more of the parameters prefixed with Service Fabric in the CortexGateway.SetParameters.xml file was not set properly when updating Gateway, or the Application Services aren’t healthy. See Troubleshooting for more information.

Test Executing Production Flows

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted)
  2. The request should return a JSON object with the output variables of the flow e.g. { "Output": "2022-03-09T07:35:16+0000" }.

  3. Cortex Innovation has now been verified and is ready to use.

3.1.2.2 - Single Server - Without HA

Information about adding Cortex Innovation to Cortex 7.2 on a single on-premise server without high availability (HA), including: information about components, supported architectures, prerequisites and installation instructions.

Single server installations with HA are not recommended for the following scenarios:

  • Production installations that are required to scale and support HA

3.1.2.2.1 - Architecture

Information about the recommended Innovation platform architecture, including component descriptions.

Architecture

Components

Component Purpose Required/Optional Server Role
Cortex Gateway Web portal that hosts applications for creating automation solutions and managing their full life-cycle, including design, development, testing, deployment, monitoring, maintenance and ultimately end-of-life. Required Web Application Server
Cortex Studio Application hosted in Cortex Gateway that provides the graphical, low-code environment for developing, testing, versioning, publishing and managing the full life-cycle of automation solutions. Required Web Application Server
Cortex Flow Debugger Service Web application that allows flows to be debugged and executed. Used by Cortex Studio to debug flows and provide block information. Required Web Application Server
Cortex API Gateway Service Application Service that routes client requests to the correct Application Services. Required Application Server
Cortex Flow Execution Service Application Service that executes automation flows. Required Application Server
Cortex Block Packages A set of files which contain the blocks that users can use to build flows. Used by the Cortex Flow Debugger Service and the Cortex Flow Execution Service. Required Web Application Server, Application Server
Cortex Gateway Databases A set of databases created automatically by Gateway which are used for storing data related to user roles, flows, etc. Hopefully, we can remove the need for Gateway Databases in the next release. Required
(End of life)
Web Application Server
SQL Server Express or SQL Server Standard Required by Cortex Gateway for creating and storing the Gateway Databases. Hopefully, we can remove the need for SQL Server in the next release. Required
(End of life)
Web Application Server
Microsoft Service Fabric Distributed systems platform that hosts the Application Services where automation solutions are deployed to. Required Application Server
Microsoft Service Fabric Explorer Web portal for monitoring and managing the Service Fabric instance that automation solutions are deployed to. Required Application Server
Particular NServiceBus Messaging platform enabling scalable, reliable and flexible asynchronous messaging between Application Services. Required Application Server
Pivotal RabbitMQ Message broker used by the NServiceBus messaging platform to transport messages asynchronously between Application Services using publish/subscribe mechanism. Required Application Server
Erlang OTP Erlang run-time required by the RabbitMQ message broker. Required Application Server

Single Server Architecture

Cortex Innovation and v7.2 can run side-by-side, allowing flows to be built and run for both of them from the same Gateway instance. They each require a different set of back-end components to be installed. Innovation can be added to a Cortex v7.2 installation by using the existing hardware. The only components shared by both Innovation and v7.2 are Gateway and its databases.

The minimum architecture for adding Innovation to a v7.2 Single Site, Single Server system is as follows:

1 Server Architecture Diagram

Next Steps?

  1. Prerequisites

3.1.2.2.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for a single server (as described in Architecture) are laid out in this guide. These must be considered before undertaking installation.

Hardware Requirements

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
Single Server
Application Server +
Web Application Server
1 4+ Recommended
Minimum
16+ Recommended
12 Minimum
160+ Recommended
135 Minimum
30+ free on installation drive
40+ free on %ProgramData% drive

Software Requirements

Server Role Windows Server1 SQL Server2 .Net PowerShell3 IIS4 Other Software
Single Server
Application Server +
Web Application Server
2019 (x64) Recommended
2016 (x64)
2019
2016
2016 Express
Framework 4.7.1 5.1 10.0.177635
10.0.143936
URL Rewrite Module 2.1
Microsoft Web Deploy 3.0 or later
Visual C++ Redistributable 2013 (x64)

Domain Requirements

The server must be on a domain and cannot be a domain controller.

DNS Requirements

The installation requires IP to hostname resolution to be available. Please ensure that you have the appropriate pointer (PTR) records configured on the DNS server for the server.

Licensing Requirements

A valid Cortex licence file and Cortex Innovation feature identifier must be procured from Cortex. The feature identifier is a GUID which will be used when configuring the Gateway installation. The licence file is needed when installing the server and it should contain that server’s fingerprint.

To get a licence file and feature identifier take the following steps:

  1. Copy the following template to a text file:

    Web Application/Application Server
    MachineID: 
    Fingerprint: 
    
    Please also include a suitable Cortex Innovation feature identifier.
    
  2. Extract Cortex Innovation 2022.9 - Licence Fingerprint Generator.zip.

  3. From that folder, copy Cortex.Licensing.FingerprintGeneration.exe to the server.

  4. Double-click Cortex.Licensing.FingerprintGeneration.exe to run it. A command line window will appear, containing a machine identifier and fingerprint, e.g:

    MachineID: SERVER
    Fingerprint: 111118BA104C928319E0CBAE30844CF8B7FD8BC414D1567844D1D0830089F1C9BF5C6
    
  5. Copy the output (machine identifier and fingerprint) to the Web Application/Application Server section of the text file created in the initial step. Note that the machine identifier can be changed to any string.

  6. Request a licence and feature identifier by raising a case in the Cortex Service Portal, including the contents of the text file containing all of the fingerprint and machine information in the body of the case.

  7. When the licence and feature identifier have arrived, copy the file Cortex.lic to %ProgramData%\Cortex\Licences on the Web Application Server, creating the Cortex and Licences folders if they don’t exist. Save the feature identifier for use when Upgrading Gateway.

Web Browser Requirements

Gateway supports the latest versions of the following browsers:

  • Chrome
  • Edge
  • Firefox

Certificate Requirements

An X.509 SSL certificate (standard or wildcard) should be used to:

  • Allow Application Services to identify themselves to clients such as Gateway.
  • Prevent unauthorised nodes from joining the single node cluster.
  • Connect to Service Fabric Explorer from the Application Server.
  • Connect to Gateway.
  • Allow Gateway to connect to the Flow Debugger Service.

The certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in one of the following formats, depending on the certificate type:
    • Standard certificates must use the standard format (e.g. CN=host.domain.com).
    • Wildcard certificates must use the wildcard format, pertaining to the domain of the server (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the API Gateway Service.
  • Subject Alternative Names (SAN): At minimum the FQDN of the server. It can also include NetBIOS Name, IP address, localhost, 127.0.0.1. It must include any additional host names that should be able to be used to access the API Gateway Service.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.
  • Key Usage extension must have a value of Digital Signature, Key Encipherment (a0).
  • Enhanced Key Usage must include Server Authentication and Client Authentication.

This file should be placed in a known location on the server. This location will be required when running the Application Server installation script.

TLS Requirements

There is a set of non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the security changes which will be applied. The Cortex.Innovation.Install.SSLBestPractices.ps1 script is provided during installation to apply these security changes to the server.

Additional Application Server Requirements

Filesystem Requirements

The server must use an NTFS filesystem.

Service Requirements

The following Windows Services must be running on the server:

  • Remote Registry
  • Windows Event Log
  • Performance Logs & Alerts

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on the server must be available to run the installation scripts. This is a prerequisite of Microsoft Service Fabric, which is the platform that Cortex Innovation is built upon.

Antivirus Exclusions

It is advised (by Microsoft Service Fabric) that the following antivirus exclusions are created on the server to reduce antivirus processing on Service Fabric artefacts:

Folder Exclusions:

  • %ProgramFiles%\Microsoft Service Fabric
  • %ProgramData%\SF
  • %ProgramData%\SF\Logs

Process Exclusions:

  • Fabric.exe
  • FabricHost.exe
  • FabricInstallerService.exe
  • FabricSetup.exe
  • FabricDeployer.exe
  • ImageBuilder.exe
  • FabricGateway.exe
  • FabricDCA.exe
  • FabricFAS.exe
  • FabricUOS.exe
  • FabricRM.exe
  • FileStoreService.exe

A script is provided during installation to add these exclusions for Windows Defender. If any other antivirus software is running, these will need to be added manually.

If adding the exclusions manually, the Process Exclusions should be done before installation occurs, as the processes will be used during installation of the application and antivirus software can cause the installation to fail or timeout. Folder Exclusions may need to be added after installation has occurred as some antivirus software needs the folders to exist.

Port Requirements

Cortex Innovation and Microsoft Service Fabric require a range of firewall ports to be opened between the server and specific services.

If you are using Windows Firewall, some ports are opened during installation and others are opened dynamically as needed. If any other firewall is used, it will be necessary to add the rules described in Port Requirements to open the correct ports.

The Cortex.Innovation.Test.PortUsage.ps1 script is provided during installation to test the ports on the server and make sure they do not overlap with any other programs; most ports may be altered if this is the case, the description will say if this is not possible.

Additional Web Application Server Requirements

Security Requirements

Installation User

Domain users must be available to run the Application Pools for Gateway and Flow Debugger Service. These users must be given Log on as a service and Log on as a batch job permissions otherwise the Application Pools will not be able to run. Information about how to do this will be given during installation.

For Flow Debugger Service, the NETWORK SERVICE user can also be used.

Domain Requirements

For Gateway, only Windows domains with an Active Directory domain controller running Active Directory Domain Services are supported.

Supported versions of Active Directory are listed below:

Version Verified? Supported From Supported Until
Windows Server 2003 Cortex v2022.9 To be evaluated
Windows Server 2003 R2 Cortex v2022.9 To be evaluated
Windows Server 2008 Cortex v2022.9 To be evaluated
Windows Server 2008 R2 Cortex v2022.9 To be evaluated
Windows Server 2012 Cortex v2022.9 To be evaluated
Windows Server 2012 R2 Cortex v2022.9 To be evaluated
Windows Server 2016 Cortex v2022.9 To be evaluated
Windows Server 2019 Cortex v2022.9 To be evaluated
Windows Server 2022 Cortex v2022.9 To be evaluated

Next Steps?

  1. Install Application Server

  1. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

  2. SQL Server Express, Standard and Enterprise are supported. Other databases are not supported. Note that Transparent Data Encryption is not supported on SQL Server Express. ↩︎

  3. PowerShell 5.1 ships with Windows Server 2016 and 2019. ↩︎

  4. IIS is supported; other web servers, including IIS Express are not supported. ↩︎

  5. Ships as a windows role within Windows Server 2019. ↩︎

  6. Ships as a windows role within Windows Server 2016. ↩︎

3.1.2.2.3 - Install Application Server

Information about installing the Application Server.

Install Application Server

This guide describes how to install the Application Server components on the server. Please ensure that the Prerequisites have been read before starting this installation.

Make Installation Artefacts Available

  1. Copy the following artefacts to a folder on the server (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - App Services.zip
    • Cortex Innovation 2022.9 - App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - App Server Install Scripts.zip file to a folder with the same name.

Install Microsoft .NET Framework 4.7.1

Microsoft Service Fabric requires a minimum of Microsoft .NET Framework 4.7.1 to be installed on the server.

To find the version of the framework that is installed:

  1. On the Start menu, choose Run.
  2. In the open box, enter regedit.exe. You must have administrative credentials to run regedit.exe.
  3. In the Registry Editor, open the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full.
  4. If the Full subkey is not present, then you do not have the .NET Framework 4.5 or later installed.
  5. Check for a DWORD value named Release. The existence of the Release DWORD indicates the .NET Framework 4.5 or newer has been installed on that computer. If the value is 461308 or over then at least .NET Framework 4.7.1 is installed and no further steps need to be taken. If it is not installed, continue with the following steps to install it.

To install .NET Framework 4.7.1:

  1. Download the .NET Framework 4.7.1 installer.
  2. Double-click on the installer file to run it.
  3. Follow the wizard to complete the installation.

These are non-compulsory security measures, recommended to be applied to the server, in order to prevent potential attacks that exploit known industry security vulnerabilities.

Applying these measures may impact other applications running on your server. Therefore, it is your responsibility to ensure that other applications and their clients will not be affected by the changes.

A collection of registry settings need to be applied to guarantee your server is only using the recommended encryption algorithms and TLS protocols. Information about these settings can be found at SSL Best Practices.

The settings can be applied by running a script. Be aware that the server will be restarted when the script is run. Apply the settings by following these instructions:

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Run the Cortex.Innovation.Install.SSLBestPractices.ps1 script using the following command:

    .\Cortex.Innovation.Install.SSLBestPractices.ps1
    

    If -Override 0 has been specified no further steps need to be taken and you can move on to the next section when the server has restarted.

  4. To use all the recommended settings click Apply all to the first prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying.

  5. Restart the machine when the script asks.

Add Antivirus Exclusions

  1. If Windows Defender is not running on the server, ensure that the Antivirus Exclusions have been added to the running antivirus software on the server and continue to the next section, otherwise follow these steps:
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS name or fully qualified domain name of the server:

      .\Cortex.Innovation.Add.WindowsDefenderExclusions.ps1 -ApplicationServers @("app-server1")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

    5. A message will indicate that the script has completed successfully.

Check Port Usage

  1. To check all necessary ports are free, follow these steps.
    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Run the Cortex.Innovation.Test.PortUsage.ps1 script using the following command, modifying the ApplicationServers value to contain the NETBIOS name or fully qualified domain name of the server:

      .\Cortex.Innovation.Test.PortUsage.ps1 -ApplicationServers @("app-server1")
      
    4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

    5. If all ports are free, the script will report the following:

      All ports required by Cortex Innovation are free

      If this is the case, continue to the next section. Otherwise, consult the messages returned by the script, which will give details about how to modify the Cortex.Innovation.Install.Config.json configuration file, in the Cortex Innovation 2022.9 - App Server Install Scripts folder, to use different ports. This will be used later during installation.

      The Cortex.Innovation.Test.PortUsage.ps1 script cannot currently re-check modified ports in the configuration file so these need to be manually checked to see that they are free.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, locate the Cortex.Innovation.Install.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1") `
        -ServerCertificatePath "C:\Install\Certificates\cert.pfx" `
        -ServerCertificatePwd "myPassword" `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt"
            
    
    .\Cortex.Install.ps1 -ConfigFileName Cortex.Innovation.Install.Config.json `
        -AppServicesPath "C:\Install\Cortex Innovation 2022.9 - App Services.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -ApiGatewayBasicAuthUserName "BasicAuthUser" `
        -ApiGatewayBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -CustomerName "Customer1" `
        -ApplicationServerIPv4Addresses @("192.168.1.1") `
        -UseSelfSignedCertificates `
        -SkipLoadBalancer `
        -Credential $Credential `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-app-install-log.txt"
            
    Name Description
    AppServicesPath Configure this value with the location of the App Services zip file on the server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the server.
    ApiGatewayBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when upgrading Gateway.
    ApiGatewayBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows). This should be Cortex Encrypted.

    This value will be needed later, when upgrading Gateway.
    CustomerName A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer.
    ApplicationServerIPv4Addresses The IPv4 address of the server.
    ServerCertificatePath The local path of a .PFX certificate file on the server. Environment variables cannot be used.

    This is only needed if installing with CA Certificates (Recommended). The certificate should meet the Certificate Requirements.

    This certificate will be used for:
    • Securing communication between the Application Services.
    • Allowing Application Services to identify themselves to clients such as Gateway.
    • Preventing unauthorised nodes from joining the single node cluster.
    • Connecting to Service Fabric Explorer from each of the Application Servers.
    ServerCertificatePwd The password for the .PFX certificate file specified in ServerCertificatePath.

    This is only needed if installing with CA Certificates (Recommended).
    UseSelfSignedCertificates Installs Application Services and required infrastructure using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    SkipLoadBalancer Installs Application Services and required infrastructure without installing a load balancer.
    Credential The credentials of the user which will be used to perform remote operations on the server. It must be a domain user that is a member of the local Administrators group on the server.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.

    The ApiGatewayBasicAuthUserName and ApiGatewayBasicAuthPwd will be needed later, when upgrading Gateway.

  3. Save and close Cortex.Innovation.Install.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1 -WhatIf
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -WhatIf -AcceptEULA
    
  5. Run the PowerShell command to test the installation script.

  6. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  7. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ.

  8. Wait for the command to finish. It will display the output of the installation command without making any changes to the system.

  9. Check that there have been no errors in the script; these would appear in red in the console.

    If there are no errors, continue to the next section; otherwise, check if the errors have any instructions for rectifying the issue and follow them.

    If there are no useful instructions, check that all previous steps have been followed correctly and, if not, rectify it and run the command again.

    If this does not work, please contact Cortex Service Portal for further assistance. The WhatIf script will have created a temporary version of the config file in the script location, showing what changes would be made to it when the script runs. The name is appended with -WhatIf (e.g. Cortex.Innovation.Install.Config-WhatIf.json). This file can be provided when obtaining support.

Run Installation Script

  1. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.ps1
    
  2. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  3. Run the PowerShell command to install HA Services and the required infrastructure.

  4. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on the server and press OK.

  5. A password prompt will appear. Enter a password which will be used to create a user in RabbitMQ. This should be entered carefully and recorded as it may be needed if seeking support from Cortex Service Portal. Press OK.

  6. Wait for the script to finish running. This should take approximately 10 minutes.

  7. Check that there have been no errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, check your configuration files, and retry the installation.

    In some circumstances, retrying may error due to components being installed already. In this case please run the following command, followed by the original installation command:

    .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer
    

    If the errors do not give any instructions on how to rectify, see Troubleshooting During Installation for further information; if this does not help then please contact Cortex Service Portal for assistance.

Check Application Services

  1. Log on to the server.

  2. Import the certificate, used in the ServerCertificatePath parameter of the Configure Installation Script section, to your Current User certificate store. This can be achieved by double clicking on the certificate .PFX file and following the wizard.

    If using self-signed certificates, the certificate can be retrieved by using the Manage Computer Certificates tool in Windows to export the CortexServerCertificate from the Personal store and then importing it to the Current User store by double-clicking on it and following the wizard.

  3. Open a web browser.

  4. Navigate to https://server.domain.com:9080/Explorer, where server.domain.com is the fully qualified domain name of the server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    The screen should resemble that in the following figure:

    Healthy Service Fabric Explorer Cluster

    The status circles should be entirely green - this indicates that the node and all services and instances are healthy. Other status pages can be accessed by expanding items in the leftmost pane. Issues can be tracked down to the failing component by expanding items with warning triangles or error icons on. The next few diagrams show the status pages for a healthy system.

    After expanding the application, clicking on any of the services should display a green circle and Status = Active:

    Healthy Service Fabric Explorer Service

    After expanding either of the services, clicking on any of the instances/partitions should display a green circle and Status = Ready:

    Healthy Service Fabric Explorer Instance

    Clicking on any of the nodes at the bottom of the leftmost pane should display a green circle and Status = Up:

    Healthy Service Fabric Explorer Node

    If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, go to the next section.

    If the warnings persist or anything on the screen goes red, expand the items to find the individual services and instances which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. Error and warning messages should be displayed on the status screens and should indicate what is wrong.

    If no useful message can be seen here, the service log files may contain more information. These can be found on the server at:

    • %ProgramData%/Cortex/Cortex API Gateway Service
    • %ProgramData%/Cortex/Cortex Flow Execution Service

    If no solution can be found, please contact Cortex Service Portal for further assistance.

Preserve installation files

Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.

Next Steps?

  1. Install Web Application Server

3.1.2.2.4 - Upgrade v7.2 Gateway to Include Innovation

Information about upgrading v7.2 Gateway with Innovation functionality.

Upgrade v7.2 Gateway to Include Innovation

This guide describes how to upgrade Gateway on v7.2 to include Innovation. Please ensure that Install Application Server has been completed before starting this installation. These steps assume that the v7.2 version of Gateway and its prerequisites have already been installed.

The steps to add Innovation functionality to 7.2 are:

  1. Install Flow Debugger Service
  2. Upgrade Gateway

Make Installation Artefacts Available

  1. Copy the following artefacts to a folder on the machine (the version numbers may differ):

    • Cortex Innovation 2022.9 - Block Packages.zip
    • Cortex Innovation 2022.9 - Gateway.zip
    • Cortex Innovation 2022.9 - Flow Debugger Service.zip
    • Cortex Innovation 2022.9 - Web App Server Install Scripts.zip
  2. Extract the Cortex Innovation 2022.9 - Web App Server Install Scripts.zip zip file to a folder with the same name.

Install Prerequisites

Licensing

Ensure that a valid Cortex licence file named Cortex.lic exists on the server, in the location %ProgramData%\Cortex\Licences. If it does not, follow the instructions located at Licensing Requirements.

Install Flow Debugger Service

Get Application Pool User

A domain user account is required for the Flow Debugger Service web application pool and must be created prior to performing the installation. In line with best practices, this account should not be used for any purposes other than those specified for the Flow Debugger Service. Alternatively, the NETWORK SERVICE user may also be used.

This user must currently have access to the default NuGet directory, in order to load block packages correctly. To add permissions for the user take the following steps:

  1. Navigate to %SystemRoot%\System32\config\systemprofile\AppData\Roaming\ and create a new folder named NuGet if one does not exist.
  2. Right-click on the NuGet folder and click Properties.
  3. In the dialog, click the Security tab.
  4. Click the Edit... button.
  5. Click the Add... button.
  6. Enter the username of the application pool user and click OK.
  7. In the Permissions section at the bottom, check Full control
  8. Click OK.

The user must be given Log on as a service and Log on as a batch job permissions. To do this take the following steps:

  1. Navigate to Start -> Administrative Tools -> Local Security Policy.
  2. In the Local Security Policy dialog, expand the Local Policies node then select User Rights Assignment.
  3. Take the following steps for the Log on as a service and Log on as a batch job policies:
    1. In the right-hand panel, double-click on the policy.
    2. In the Properties dialog, click on the Add User or Group button.
    3. Type the name of the application pool user account into the Enter the object names to select text box. Click the Check Names button to confirm that the user exists.
    4. Click OK on the Select Users dialog, and then confirm the user is correct by clicking OK on the Properties dialog.

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.FlowDebuggerService.ps1 script and open it with a text editor.

  2. Choose the tab below that matches the configuration for this installation, then update the script to match, changing the parameters according to the details given below:

    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    
    .\Cortex.Install.FlowDebuggerService.ps1 `
        -FlowDebuggerServicePath "C:\Install\Cortex Innovation 2022.9 - Flow Debugger Service.zip" `
        -BlockPackagesPath "C:\Install\Cortex Innovation 2022.9 - Block Packages.zip" `
        -FlowDebuggerBasicAuthUserName "BasicAuthUser" `
        -FlowDebuggerBasicAuthPwd "ADA9883B11BD4CDC908B8131B57944A4" `
        -UseSelfSignedCertificates `
        -Credential $AppPoolIdentity `
        -AcceptEULA:$AcceptEula `
        *>&1 | Tee-Object -FilePath "cortex-flow-debugger-service-install-log.txt"
            
    Name Description
    FlowDebuggerServicePath Configure this value with the location of the Flow Debugger Service zip file on the server.
    BlockPackagesPath Configure this value with the location of the Block Packages zip file on the server.
    FlowDebuggerBasicAuthUserName Configure this value with the username that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    For security reasons it is recommended that the default value BasicAuthUser should be changed.

    Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.

    This value will be needed later, when upgrading Gateway.
    FlowDebuggerBasicAuthPwd Configure this value with the password that will be used for Basic Authentication when Gateway makes HTTPS requests to the Flow Debugger Service.

    This password should be Cortex Encrypted. For security reasons it is recommended that the default value ADA9883B11BD4CDC908B8131B57944A4 should be changed.

    This value will be needed later, when upgrading Gateway.
    UseSelfSignedCertificates Enables Flow Debugger Service to communicate with Gateway using generated Self-Signed Certificates rather than CA Certificates.

    Not recommended for production use.
    Credential The credentials of the user that will be used to run the Debugger application pool in IIS.

    This does not need to be changed, a prompt will appear to enter this information when the script is run.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.FlowDebuggerService.ps1.

Run Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.FlowDebuggerService.ps1
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  5. Run the PowerShell command to install the Flow Debugger Service.

  6. A credentials prompt will appear. Enter the credentials of the user that should run the Debugger application pool in IIS. If using the NETWORK SERVICE user, enter any user as the username and leave the password blank; the NETWORK SERVICE user will need to be selected in the final step.

  7. Wait for the script to finish running. This should take approximately 2 minutes.

  8. An error may have appeared saying:

    The Windows Process Activation Service service is not started.
    

    This can be ignored.

  9. Check that there have been no other errors in the script; these would appear in red in the console.

    If there are any errors, then please follow any instructions given within them to rectify the situation, and retry the installation.

    If the errors do not give any instructions on how to rectify, please contact Cortex Service Portal for further assistance.

  10. If using NETWORK SERVICE for the application pool user:

    1. Open Internet Information Services (IIS) Manager.
    2. On the left, expand the server node.
    3. Click Application Pools.
    4. Right-click on the Debugger application pool and select Advanced Settings....
    5. In the Advanced Settings dialog, click on Identity and then click the ellipses (...).
    6. In the Application Pool Identity dialog, select Built-in account, then select NetworkService from the drop-down, then click OK.
    7. Right-click on the Debugger application pool and click Recycle....

Upgrade Gateway

Configure Installation Script

  1. In the Cortex Innovation 2022.9 - Web App Server Install Scripts folder, locate the Cortex.Innovation.Install.Gateway.ps1 script and open it with a text editor.

  2. Configure the script according to the details given below:

    .\Cortex.Install.Gateway.ps1 `
    -GatewayPackagePath "C:\Install\Cortex Innovation 2022.9 - Gateway.zip" `
    -GatewayApplicationIISPath "Cortex\gateway" `
    -FeatureFlags "InnovationId" `
    -ServiceFabricApiGatewayEndpoint "https://server.domain.com:8722/" `
    -ServiceFabricUsingSelfSignedCertificates $false `
    -ServiceFabricApiGatewayBasicAuthUsername "BasicAuthUser" `
    -ServiceFabricApiGatewayBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerEndpoint "https://server.domain.com/debugger/api/" `
    -DotNetFlowDebuggerBasicAuthUsername "BasicAuthUser" `
    -DotNetFlowDebuggerBasicAuthPassword "ADA9883B11BD4CDC908B8131B57944A4" `
    -DotNetFlowDebuggerUsingSelfSignedCertificates $false `
    -Test:$Test `
    -AcceptEULA:$AcceptEula `
    *>&1 | Tee-Object -FilePath "cortex-gateway-install-log.txt"
    
    Name Description
    GatewayPackagePath Configure this value with the location of the Cortex Innovation 2022.9 - Gateway.zip file on the installation server.
    GatewayApplicationIISPath Change to the correct Site Name/Application if either was modified from the defaults (Cortex/gateway) when creating the website or application.
    FeatureFlags Replace InnovationId with the Cortex Innovation feature identifier, which should have been provided by Cortex when fulfilling the Licensing Requirements, if it wasn’t it should be requested using Cortex Service Portal.

    This will overwrite the FeatureFlags value in the Gateway web.config.
    ServiceFabricApiGatewayEndpoint Replace server.domain.com with the fully qualified domain name of the server. The port should be specified as 8722 and there must be a trailing slash, e.g. https://server.domain.com:8722/.

    This will overwrite the ServiceFabricApiGatewayEndpoint value in the Gateway web.config.
    ServiceFabricUsingSelfSignedCertificates Configure the value as $false if you used valid CA certificates when installing the Application Server, $true if you used self-signed certificates.

    This will overwrite the ServiceFabricUsingSelfSignedCertificates value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthUsername This must be changed if you used a non-default ApiGatewayBasicAuthUserName when installing the Application Server; if so, this value must be configured to the one used.

    This will overwrite the ServiceFabricApiGatewayBasicAuthUsername value in the Gateway web.config.
    ServiceFabricApiGatewayBasicAuthPassword This must be changed if you used a non-default ApiGatewayBasicAuthPassword when installing the Application Server; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will overwrite the ServiceFabricApiGatewayBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerEndpoint Replace server.domain.com with the fully qualified domain name of the Web Application Server.

    This will overwrite the DotNetFlowDebuggerEndpoint value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthUsername This must be changed if you used a non-default FlowDebuggerBasicAuthUserName when installing the Flow Debugger Service; if so, this value must be configured to the one used.

    This will overwrite the DotNetFlowDebuggerBasicAuthUsername value in the Gateway web.config.
    DotNetFlowDebuggerBasicAuthPassword This must be changed if you used a non-default FlowDebuggerBasicAuthPassword when installing the Flow Debugger Service; if so, this value must be configured to the one used. It can be Cortex Encrypted.

    This will overwrite the DotNetFlowDebuggerBasicAuthPassword value in the Gateway web.config.
    DotNetFlowDebuggerUsingSelfSignedCertificates Configure the value as $false if you are using valid CA certificates to secure the site containing Gateway and Flow Debugger Service, $true if using self-signed certificates.

    This will overwrite the DotNetFlowDebuggerUsingSelfSignedCertificates value in the Gateway web.config.
    Test This does not need to be changed, it will be set at a later stage.
    AcceptEULA This does not need to be changed, the EULA will be accepted at a later stage.
    FilePath The filename that installation logs are written to. If this should be written to a different location than where the installation files are then a full path should be specified.
  3. Save and close Cortex.Innovation.Install.Gateway.ps1.

Test Installation Script

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - Web App Server Install Scripts folder using the following command, modifying the path as necessary:

    cd "C:\Install\Cortex Innovation 2022.9 - Web App Server Install Scripts"
    
  3. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1 -Test
    
  4. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -Test -AcceptEULA
    
  5. Run the PowerShell command to test the configuration. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

Run Installation Script

  1. Ensure the Gateway application pool is stopped:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Stop.
  2. Type the following command into PowerShell:

    .\Cortex.Innovation.Install.Gateway.ps1
    
  3. Please read the End User Licence Agreement which can be found here. Once you agree to the terms, add the flag -AcceptEULA to the command entered above, e.g:

    .\<CortexInnovationInstallScriptName>.ps1 -AcceptEULA
    
  4. Run the PowerShell command to install Gateway. In the event of any errors, there will be an error message displayed at the end of the output with a line confirming the Error Count.

  5. Start the Gateway application pool:

    1. Open Internet Information Service (IIS) Manager.
    2. In the left pane, expand the server node.
    3. Click Application Pools to display a list of the Application Pools.
    4. Right-click the Cortex Gateway application pool and select Start.
  6. Once the application pool has been started, the site will be available on <protocol>://<host>:<port>/<webapplicationname>, e.g. https://localhost/gateway.

Next Steps?

  1. Try it out

3.1.2.2.5 - Try it out

Information about trying out Cortex Innovation for the first time.

Try it out

This guide describes how to try out a new Innovation installation to make sure it is working. Please ensure that Setup Gateway has been completed before taking these steps.

Test Debugging Flows

Test the platform by creating a new flow and executing it using the following steps:

  1. Click on the Flows charm, then the + button and click Group to open a dialog.
  2. Enter a name for the group, configure the Permission Groups and click OK to create the group.
  3. Click on the group to open it (refresh the page if it does not appear).
  4. Inside the group, click the + button again and click on Flow(Innovation) to open a dialog. If the menu item is not present, it means that the FeatureFlags in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway. See Troubleshooting for more information.
  5. Enter a name for the flow, configure the Permission Groups and click OK to create the flow.
  6. The flow should be displayed with a start flow block and end flow block. A list of block palettes should be displayed down the left hand side:

    New Flow - Number of palettes may differ

    If the blocks in the flow do not display or the palettes are not visible, see Troubleshooting for more information.
  7. Add a Set Variable block and connect it between the start and end blocks.
  8. Click the Set Variable block to open the Property Editor.
  9. Set the Value property to the expression DateTimeOffset.Now.
  10. Type Result into the Variable property and click Create Result.
  11. In the Variable Editor, set Is Output Variable? to true for the new Result variable.
  12. Set a breakpoint on the end block and start the flow. An execution token should appear, the Result variable should show the current time. If the token does not appear, try refreshing the page.
  13. Continue or stop the execution.
  14. Commit the flow.

Test Publishing Production Flows

  1. Log in to Gateway with a user that has the Admin role.
  2. Click on the Settings charm, then Packages.
  3. Click Add Package Definition. Enter a package name and select the new flow to add to the package. Click Save to save the new package.
  4. Click Publish. A success message should appear. If it doesn’t it means that either one or more of the parameters prefixed with Service Fabric in the CortexGateway.SetParameters.xml file was not set properly when installing Gateway, or the Application Services aren’t healthy. See Troubleshooting for more information.

Test Executing Production Flows

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted)
  2. The request should return a JSON object with the output variables of the flow e.g. { "Output": "2022-03-09T07:35:16+0000" }.

  3. Cortex Innovation has now been verified and is ready to use.

3.1.3 - Add Observability to Innovation

Information about installing an observability platform for Innovation.

3.1.3.1 - Grafana

Information about adding a Grafana platform to Innovation, including details about components, supported architectures, prerequisites, installation and configuration instructions.

For instructions on how to set up Grafana and Grafana Loki in the cloud see Grafana Cloud.

3.1.3.1.1 - Architecture

Information about the recommended architecture for a Grafana platform installation.

Architecture

Components

Component Purpose Required/Optional Server Role
Grafana Web application that provides querying and visualisation of data in the form of dashboards. Required Web Application Server
Grafana Loki Log aggregation system designed to store and query logs from applications and infrastructure. Required Web Application Server
Microsoft Internet Information Services (IIS) Web server used as a reverse proxy for Grafana Loki. Required Web Application Server
Promtail An agent which ships the contents of local logs to a Grafana Loki instance. It should be deployed to every machine that has a Microsoft Service Fabric node used by Innovation. Required Application Server

The following architecture requires 1 + 1..n servers:

  • 1 x Web Application Server which contains Grafana, Grafana Loki and Microsoft IIS.
  • 1..n x Application Servers.

Next Steps?

  1. Prerequisites

3.1.3.1.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for each server role (as described in Architecture) are laid out in this guide. These must be considered before undertaking the installation.

Hardware Requirements

Option 1: Install on New Hardware

The following hardware requirements are recommended for production systems:

Server Role Servers Required CPU Cores (> 2GHz) RAM (GB) Disk (GB)
Web Application Server 1 4+ Recommended
Minimum
16+ Recommended
Minimum
50+ (SSD) Recommended
40 (HDD) Minimum
5+ free on installation drive

Option 2: Install on Existing Hardware

If additional hardware is not available, it is possible to install to the same Web Application server that hosts Cortex Gateway.

The table below specifies additional resources that are recommended to be added to the existing Web Application server:

Server Role Additional CPU Cores (> 2GHz) Additional RAM (GB) Additional Disk (GB)
Web Application Server
(Shared with Cortex Gateway)
4+ Recommended
Minimum
12+ Recommended
Minimum
10+ Recommended
Minimum

Software Requirements

Server Role Windows Server1 IIS2 Other Software
Web Application Server 2019 (x64) Recommended
2016 (x64)
10.0.177633
10.0.143934
IIS Basic Authentication5
URL Rewrite module 2.1
Grafana 8.5.4 Enterprise Edition
Grafana Loki 2.5.0
Application Server 2019 (x64) Recommended
2016 (x64)
Promtail 2.5.0

Domain Requirements

All servers must be on the same domain and cannot be domain controllers.

Web Browser Requirements

Grafana supports the latest versions of the following browsers:

  • Chrome/Chromium
  • Firefox
  • Safari
  • Microsoft Edge

Additional Web Application Server Requirements

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on the Web Application Server must be available to perform the installation.

Port Requirements

The observability platform requires a range of firewall ports to be opened on the Web Application Server.

Certificate Requirements

An X.509 SSL certificate (standard, wildcard or self-signed) should be used to secure communication between:

  • Promtail on the Application Servers and the reverse proxy configured for Grafana Loki on the Web Application Server.
  • Grafana end users and the Grafana Web Application on the Web Application Server.

The wildcard certificate used for installing Innovation can be used if it is available in the .PEM file format, otherwise a new certificate can be obtained from a Certificate Authority, such as Let’s Encrypt, and must meet the following requirements:

  • Subject field must be in one of the following formats, depending on the certificate type:
    • Standard certificates must use the standard format (e.g. CN=host.domain.com).
    • Wildcard certificates must use the wildcard format, pertaining to the domain of the Web Application Server (e.g. CN=*.domain.com).
  • Subject alternative names must include any additional host names that should be able to be used to access the Grafana Web Application.
  • Certificate file must be in a .PFX file format, with a known password.
  • Certificate file must also be available in a .PEM file format.
  • Certificate file must contain the full chain of certificates.
  • Certificate file must include the private key.

The files should be placed in a known location on the Web Application Server. This location will be required when configuring Grafana to use HTTPS.

More information about importing the certificate is given during installation.

TLS Requirements

A set of non-compulsory security measures is recommended to be applied to the Web Application Server to prevent attacks that exploit known industry security vulnerabilities. This includes disabling all versions of SSL and TLS apart from TLS 1.2, and disabling all cipher suites apart from the following:

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

See SSL Best Practices for a full list of the recommended security changes to be applied.

Apply the settings by following these instructions:

  1. Copy from one of the application servers the Cortex.Innovation.Install.SSLBestPractices.ps1 file extracted during the Make Installation Artefacts Available step into a suitable location on the Web Application Server.

  2. Open a Windows PowerShell (x64) window as administrator.

  3. Change the location to the folder where the Cortex.Innovation.Install.SSLBestPractices.ps1 file was copied to using the following command, modifying the path as necessary:

    cd "C:\Install"
    
  4. Run the Cortex.Innovation.Install.SSLBestPractices.ps1 script using the following command:

    .\Cortex.Innovation.Install.SSLBestPractices.ps1
    
  5. To use all the recommended settings click Apply all to the first prompt.

    To selectively apply each setting select Choose which to apply. Each change will then be prompted with a Yes/No confirmation before applying.

  6. Restart the machine when the script asks.

Additional Application Server Requirements

These requirements apply to each of the Application Servers.

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on all Application Servers must be available to perform the installation.

Next Steps?

  1. Install Grafana

  1. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

  2. IIS is supported; other web servers, including IIS Express are not supported. ↩︎

  3. Ships as a windows role within Windows Server 2019. ↩︎

  4. Ships as a windows role within Windows Server 2016. ↩︎

  5. Installed during the Install IIS Basic Authentication configuration steps. ↩︎

3.1.3.1.3 - Install Grafana

Information about installing and configuring Grafana on the Web Application Server.

3.1.3.1.3.1 - Install Grafana

Information about installing Grafana on the Web Application Server.

Install Grafana

This guide describes how to install Grafana on the Web Application Server. Please ensure that the Prerequisites have been completed before starting this installation.

Install Grafana

  1. Download the Grafana 8.5.4 Windows installer.
  2. Run the installer and install Grafana to a suitable location.

Next Steps?

  1. Configure Grafana

3.1.3.1.3.2 - Configure Grafana

Information about configuring Grafana on the Web Application Server.

Configure Grafana

This guide describes how to configure Grafana on the Web Application Server.

Log-in and Change the Password

It is required that on the first log in into Grafana, a new password for the admin user is set up. The password should be different from the default one.

  1. On the Web Application Server open a web browser.
  2. Browse to http://localhost:3000/.
  3. On the login page, enter admin for the username and password.
  4. Click Log in.
  5. Set a new password for the admin user when prompted to do so.

Configure HTTPS

By default Grafana allows access over the unsecure HTTP protocol. This needs to be modified to allow access only over the secure HTTPS protocol.

  1. Locate sample.ini file in the grafana\conf subfolder in the location Grafana was installed to; by default C:\Program Files\GrafanaLabs\grafana\conf\sample.ini.

  2. Copy sample.ini and paste it in the same location renaming it to custom.ini.

  3. Run a text editor in administrator mode.

  4. In the text editor open the custom.ini Grafana configuration file.

  5. In the server section uncomment the protocol option and set it to HTTPS, e.g.:

    # Protocol (http, https, h2, socket)
    protocol = https
    
  6. In the server section uncomment the cert_file and cert_key options and set them to the certificate .pem and .key filenames and path saved to during the Certificate Requirements step e.g.:

    # https certs & key file
    cert_file = C:\certificates\certificate.pem
    cert_key = C:\certificates\certificate.key
    
  7. Save the file.

  8. Open the Services app.

  9. Restart the Grafana service.

Verify That HTTPS Works

It is important to verify that Grafana is only accessible through HTTPS.

  1. On the Web Application Server open a web browser.
  2. Browse to http://localhost:3000/.
  3. Browser should not be able to make a connection to Grafana and a default error page should be displayed.
  4. Browse to https://localhost:3000/.
  5. On the login page, enter admin as the username and the corresponding password.
  6. Click Log in.
  7. You should have successfully logged into Grafana.

Next Steps?

  1. Install Grafana Loki

3.1.3.1.4 - Install Grafana Loki

Information about installing and configuring Grafana Loki on the Web Application Server.

3.1.3.1.4.1 - Install Loki

Information about installing Grafana Loki on the Web Application Server.

Install Loki

This guide describes how to install Grafana Loki on the Web Application Server. Please ensure that the Prerequisites have been completed before starting this installation.

Install Grafana Loki

  1. Download Grafana Loki 2.5.0 archive.
  2. Extract content of the downloaded archive to a suitable location, e.g. C:\Loki.
  3. Download the Grafana Loki Install.zip archive and extract its contents alongside the previously extracted Grafana Loki loki-windows-amd64.exe. This archive contains the loki-local-config.yaml configuration file, NSSM (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Grafana Loki as a Windows service.
  4. Run Windows PowerShell as Administrator.
  5. Change the location to where all the files were extracted to.
  6. Execute the .\Install-Loki.ps1 command to install the downloaded Grafana Loki loki-windows-amd64.exe as a service.
  7. Execute the .\Start-Loki.ps1 command to start the Grafana Loki service.

Next Steps?

  1. Configure Loki

3.1.3.1.4.2 - Configure Loki

Information about configuring Grafana Loki on the Web Application Server.

Configure Loki

This guide describes how to configure Grafana Loki on the Web Application Server.

Install Certificate

IIS requires the X.509 SSL certificate, obtained in the prerequisites, to be installed on the Web Application Server.

You can import the certificate by right clicking the certificate file, selecting Install Certificate and following the wizard. When prompted, ensure you import it into the Local Machine store and not Current User.

To verify the certificate is imported:

  1. Click the Windows button (Start)
  2. Type certlm.msc and press Enter to open the Certificate Manager dialog
  3. Expand Personal and select Certificates
  4. You should see your certificate in this store

Setup Reverse Proxy with IIS

All of the steps must be carried out on the Web Application Server.

Install IIS Basic Authentication

  1. Run Server Manager.
  2. Expand the Manage menu and select Add Roles and Features.
  3. In the left-hand menu, select Server Selection.
  4. Select the name of the Web Application Server, click Next.
  5. On the Server Roles page, in the Roles tree, expand Web Server (IIS) –> Web Server –> Security.
  6. Select Basic Authentication, click Next.
  7. Click Next to get to the Confirm installation selections page.
  8. Click Install.
  9. Click Close on the Results page.

Install IIS URL Rewrite Module

  1. Download the URL Rewrite module 2.1
  2. Run the downloaded installer.
  3. When prompted by the Web Platform Installer, click Install.
  4. On the Prerequisites page click I Accept to agree to the license terms for the module.
  5. Once the install has completed, click Finish.
  6. Click Exit to close the Web Platform Installer.

Install Application Request Routing

  1. Download Application Request Routing 3.0
  2. Run the downloaded installer.
  3. When prompted by the Web Platform Installer, click Install.
  4. On the Prerequisites page click I Accept to agree to the license terms for the module.
  5. Once the install has completed, click Finish.
  6. Click Exit to close the Web Platform Installer.

Set Up Reverse Proxy

To set up a reverse proxy, carry out the following configuration.

Add a New Website

  1. Run IIS Manager.
  2. In the Connection pane, expand the server.
  3. Right-click on Sites and select Add Website… from the menu.
  4. In the Add Website window:
    • Provide the site name, e.g. Grafana Loki.
    • Set the Physical path to the location where the site will be stored and ensure that the path exists, e.g. C:\inetpub\wwwroot\Grafana Loki.
    • For Binding set:
      • Type: https
      • IP address: All unassigned
      • Port: 2100
    • Host name: The fully qualified domain name of the Web Application Server. This must match one of the Subject Alternative Names in the SSL certificate selected in the next step.
    • SSL certificate: Select the certificate created as part of the Certificate Requirements instructions.
    • Click OK to add the website.

Enable Basic Authentication

  1. In the Connection pane, browse to Sites.
  2. Select the newly created website.
  3. Double-click on the Authentication icon.
  4. Disable Anonymous Authentication.
  5. Enable Basic Authentication.

Configure URL Rewrite Rule

  1. In the Connection pane, browse to Sites.
  2. Select the newly created website.
  3. Double-click on the URL Rewrite icon.
  4. In the Actions pane, click Add Rule(s)….
  5. Select Reverse Proxy from the Inbound and Outbound Rules section.
  6. Click OK.
  7. If prompted to Add Reverse Proxy Rules, click OK to enable proxy functionality.
  8. In the Inbound Rules section enter localhost:3100 as the server name.
  9. Ensure that Enable SSL Offloading is checked.
  10. Click OK.

Restart the Website

  1. In the Connection pane, browse to Sites.
  2. Select the newly created website.
  3. In the Manage Website pane, click Restart.

Create Loki User

  1. Run Windows PowerShell as Administrator.

  2. Execute the following command to create a new local user on the Web Application Server:

    New-LocalUser "<username>" -Password (ConvertTo-SecureString "<password>" -AsPlainText -force) -FullName "<name>" -Description "<description>" PasswordNeverExpires
    
    Parameter Description
    username The username of the user to be created.
    password The password for the user account.
    name The full name for the user account.
    description The description of the user account.

Next Steps?

  1. Install Promtail

3.1.3.1.5 - Install Promtail

Information about installing and configuring Promtail on the Application Server(s).

3.1.3.1.5.1 - Install Promtail

Information about installing Promtail on the Application Server(s).

Install Promtail

This guide describes how to install Promtail on the Application Server(s). Please ensure that the Prerequisites have been completed before starting this installation.

Install Promtail

  1. Download Promtail 2.5.0 archive.
  2. Extract content of the downloaded archive to a suitable location, e.g. C:\Promtail.
  3. Download the Promtail Install.zip archive and extract its contents alongside the previously extracted Promtail promtail-windows-amd64.exe. This archive contains the promtail-local-config.yaml configuration file, NSSM (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Promtail as a Windows service.
  4. Run Windows PowerShell as Administrator
  5. Change the location to where all the files were extracted to.
  6. Execute the .\Install-Promtail.ps1 command to install the downloaded promtail-windows-amd64.exe as a service.

Next Steps?

  1. Configure Promtail

3.1.3.1.5.2 - Configure Promtail

Information about configuring Promtail on the Application Server(s).

Configure Promtail

This guide describes how to configure Promtail on the Application Server(s).

Install Certificate

If a self-signed certificate was obtained in the prerequisites, the CA certificate used to create this certificate must be imported on each Application Server. Otherwise, Promtail will not be able to establish communication with Grafana Loki.

To import the CA certificate:

  1. Copy the cortexCA.pfx CA certificate created during the root CA certificate generation steps into a suitable location on the Application Server.
  2. Double click on the cortexCA.pfx file to import the certificate into the Windows Certificate Store.
  3. Select Local Machine then click Next.
  4. Click Next.
  5. Enter the Export Password which the certificate was generated with then click Next.
  6. Select Place all certificates in the following store.
  7. Click Browse….
  8. Select Trusted Root Certification Authorities, click OK then click Next.
  9. Click Finish.

Configure Promtail

Set Client URL for Grafana Loki

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.

  2. Set the Grafana Loki URL in the clients section.

    The following template has been provided for convenience: https://<username>:<password>@<loki host address>:<loki reverse proxy port>/loki/api/v1/push

    Element Description
    username The username of the user created during Create Loki User steps.
    password The password which was set for the user during Create Loki User steps.
    loki host address The host address of the machine where the Grafana Loki reverse proxy was configured during Add a New Website steps . This must match the configured host name.
    loki reverse proxy port The port of the Grafana Loki reverse proxy configured during Add a New Website steps. Usually 2100.

    A correct URL should be similar to https://username:password@hostaddress:2100/loki/api/v1/push.

  3. Save the file.

Set the positions.yaml File Path

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.
  2. Set the filename in the positions section to the location where you want the positions.yaml file to be created on Promtail startup.
  3. Create all the folders of the path specified in the previous step.
  4. Save the file.

Set the Path to the Cortex API Gateway Service Log Files

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.
  2. Set the __path__ in the static_configs > targets > labels section to the path of the Logs folder specified in the appSettings.json file during installation of the Cortex API Gateway Service, e.g. "C:/ProgramData/Cortex/Cortex API Gateway Service/Logs/*.json".
  3. Save the file.

Start Promtail

  1. Run Windows PowerShell as Administrator.
  2. Change the location to the folder where the promtail-windows-amd64.exe file is located.
  3. Execute the .\Start-Promtail.ps1 command to start the Promtail Windows service.

Next Steps?

  1. Setup Grafana

3.1.3.1.6 - Setup Grafana

Information about setting up Grafana to communicate with the installed Grafana Loki as well as importing and configuring the default set of dashboards.

Setup Grafana

This guide describes where to get the default Cortex Innovation Dashboards from and how to import them for use in Grafana.

Please ensure that the Installations for Grafana and Loki have been completed before starting this section.

Configure Loki Data Source in Grafana

  1. Log in to your configured Grafana instance with a user that has the admin role.

  2. In Grafana, go to Configuration > Data Sources via the cog icon on the left sidebar.

  3. Click the big Add data source button.

  4. Choose Loki from the list.

  5. Configure the data source as follows:

    Option Description Value
    Name The name of the data source to use in Grafana Cortex Loki
    URL The address of your Grafana Loki Server http://localhost:3100
    Timeout The HTTP request timeout in seconds set to the same value as configured in the Grafana Loki loki-local-config.yaml configuration file located alongside the Grafana Loki loki-windows-amd64.exe file. 600
  6. Click Save and Test.

  7. Data source connected and labels found. message should be displayed above the Save and Test

Download the Cortex Innovation Default Dashboards

  1. Download Grafana.Dashboards.zip archive containing the Cortex Innovation default dashboards.
  2. Extract the content of the downloaded archive to a suitable location.

Create Folder for Dashboards

  1. Log in to your configured Grafana with a user that has the Admin role.
  2. To create a folder, click the + icon in the side menu, and then click Folder.
  3. Enter a folder name, e.g. Cortex.
  4. Click Create.

Import Dashboards

  1. Log in to your configured Grafana with a user that has the Admin role.

  2. To import a dashboard, click the + icon in the side menu, and then click Import.

  3. Click the Upload JSON file button.

  4. Locate the Flow Execution Requests.json file extracted from the downloaded Grafana.Dashboards.zip.

  5. Select the file and click Open.

  6. Select the folder in Grafana you wish the dashboard to be saved in, e.g. Cortex.

  7. Select your configured Loki data source from the dropdown menu.

  8. Click Import.

  9. Repeat steps 2 - 8 for the Platform Health.json file.

Configure Data Sources

It is necessary to update the Custom Filter inside the dashboards to use the correct data source.

To do this, follow these steps for all default Cortex Innovation dashboards imported:

  1. Log in to your configured Grafana with a user that has the Admin role.
  2. To open a dashboard:
    1. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.
    2. Click the folder name that the dashboards were imported to.
    3. Click the Flow Execution Requests dashboard to open it.
  3. Open the Dashboard Settings menu via the cog icon in the top right-hand side of the dashboard.
  4. Click Variables on the left-hand side of the page.
  5. Click Custom Filter at the bottom of the Variables list.
  6. Select your configured Loki data source in the Options > Data source drop-down menu.
  7. Click Update.
  8. Click the back button on the top left corner of the page to go back to the dashboard.
  9. Click the + icon next to the Custom Filter to confirm that a list of available filter options is visible.
  10. Repeat steps 2 - 9 for the Platform Health dashboard.

Next Steps?

  1. Try it Out

3.1.3.1.7 - Try it Out

Information about trying out Grafana Observability Dashboards for the first time.

Try it Out

Check Dashboards are Displaying Data

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL For HA installation use:
    https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://load-balancer&#46;domain&#46;com/api/default/default/flows/NewFlow/executions?packageName=NewPackage

    For non-HA installation use:
    https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://server&#46;domain&#46;com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services. See HA Installation script configuration or Non-HA Installation script configuration for the value specified.
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted). See HA Installation script configuration or Non-HA Installation script configuration for the value specified.
  2. Once the request has completed, using a web browser, log in to your configured Grafana.

  3. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.

  4. Click the folder name that the dashboards were imported to.

  5. Click the Flow Execution Requests dashboard to open it.

  6. The request made at step 1 should be visible on the dashboard.

  7. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.

  8. Click the folder name that the dashboards were imported to.

  9. Click the Platform Health dashboard to open it.

  10. The request made at step 1 should be visible on the dashboard.

3.1.3.1.8 - Advanced Setup

Supporting information about installing and configuring a Grafana observability platform for Cortex Innovation.

3.1.3.1.8.1 - Create Self-Signed Certificates

Information about creating and installing self-signed certificates.

Create Self-Signed Certificates

Self-signed certificates should be generated using OpenSSL which is bundled in the Cortex Web Application Server Installation Scripts:

Setup OpenSSL in PowerShell

  1. Open a Windows PowerShell (x64) window as administrator.

  2. Make a directory in which to store the certificates by running the following command, changing the path as required:

    mkdir C:\Certificates
    
  3. Navigate PowerShell to inside the certificates folder created above, using the following command, modifying the path as necessary:

    cd "C:\Certificates"
    
  4. Temporarily add OpenSSL to the Path environment variable of your system by running the following command, modifying the path according to the location of openssl.exe in the installation scripts on the machine:

    $env:PATH += ";C:\Cortex Innovation 2022.9 - Web App Server Install Scripts\OpenSSL"
    

Generate the Root CA Certificate

  1. Create the root CA private key by running the following command:

    openssl genrsa -out cortexCA.key 4096
    
  2. Generate the root CA certificate signed with the private key:

    1. Copy the following text into a text editor:

      RANDFILE        = .rnd
      [ ca ]
      default_ca      = CA_default    # The default ca section
      [ CA_default ]
      # Directory and file locations.
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md        = sha256
      policy            = policy_strict
      [ policy_strict ]
      # The root CA should only sign intermediate certificates that match.
      # See the POLICY FORMAT section of `man ca`.
      countryName             = match
      stateOrProvinceName     = match
      organizationName        = match
      organizationalUnitName  = optional
      commonName              = supplied
      emailAddress            = optional
      [ req ]
      # Options for the `req` tool (`man req`).
      default_bits        = 2048
      distinguished_name  = req_distinguished_name
      string_mask         = utf8only
      
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md          = sha256
      # Extension to add when the -x509 option is used.
      x509_extensions     = v3_ca
      [ req_distinguished_name ]
      countryName             = Country Name (2 letter code)
      countryName_min         = 2
      countryName_max         = 2
      stateOrProvinceName     = State or Province Name (full name)
      localityName            = Locality Name (eg, city)
      0.organizationName      = Organization Name (eg, company)
      organizationalUnitName  = Organizational Unit Name (eg, section)
      commonName              = Common Name (eg, your website's domain name)
      commonName_max          = 64
      emailAddress            = Email Address
      emailAddress_max        = 40
      # Optionally, specify some defaults.
      countryName_default             = GB
      stateOrProvinceName_default     = Hampshire
      localityName_default            = Southampton
      0.organizationName_default      = Cortex Ltd
      organizationalUnitName_default  = Cortex 
      emailAddress_default            = info@cortex.co.uk
      [ v3_ca ]
      # Extensions for a typical CA (`man x509v3_config`).
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid:always,issuer
      basicConstraints = critical, CA:true
      keyUsage = critical, digitalSignature, cRLSign, keyCertSign
      
    2. Save the file as ca.cnf in the directory created for the certificates above.

    3. In the PowerShell window, run the following command:

      openssl req -sha256 -x509 -new -nodes -key cortexCA.key -days 3650 -out cortexCA.pem -config ca.cnf
      
    4. Press Enter for all parameters except the Common Name. For this enter Cortex CA.

  3. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command:

    openssl pkcs12 -export -inkey cortexCA.key -in cortexCA.pem -out cortexCA.pfx
    
  4. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr.

Import the Root CA Certificate

  1. Double click on the cortexCA.pfx file in the certificates folder to import the certificate into the Windows Certificate Store.
  2. Select Local Machine then click Next.
  3. Click Next.
  4. Enter the Export Password which the certificate was generated with then click Next.
  5. Select Place all certificates in the following store.
  6. Click Browse….
  7. Select Trusted Root Certification Authorities, click OK then click Next.
  8. Click Finish.

Generate the Certificate

  1. Create a private key for the SSL cert by running the following command:

    openssl genrsa -out cortex.key 2048
    
  2. Generate the SSL certificate request:

    1. Copy the following text into a text editor:

      RANDFILE        = .rnd
      [ ca ]
      default_ca      = CA_default    # The default ca section
      [ CA_default ]
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md        = sha256
      policy            = policy_loose
      [ policy_loose ]
      # Allow the intermediate CA to sign a more diverse range of certificates.
      # See the POLICY FORMAT section of the `ca` man page.
      countryName             = optional
      stateOrProvinceName     = optional
      localityName            = optional
      organizationName        = optional
      organizationalUnitName  = optional
      commonName              = supplied
      emailAddress            = optional
      [ req ]
      # Options for the `req` tool (`man req`).
      default_bits        = 2048
      distinguished_name  = req_distinguished_name
      string_mask         = utf8only
      # SHA-1 is deprecated, so use SHA-2 instead.
      default_md          = sha256
      # Extension to add when the -x509 option is used.
      x509_extensions     = v3_req
      req_extensions      = v3_req
      [ req_distinguished_name ]
      countryName             = Country Name (2 letter code)
      countryName_min         = 2
      countryName_max         = 2
      stateOrProvinceName     = State or Province Name (full name)
      localityName            = Locality Name (eg, city)
      0.organizationName      = Organization Name (eg, company)
      organizationalUnitName  = Organizational Unit Name (eg, section)
      commonName              = Common Name (eg, your website's domain name)
      commonName_max          = 64
      emailAddress            = Email Address
      emailAddress_max        = 40
      # Optionally, specify some defaults.
      countryName_default             = GB
      stateOrProvinceName_default     = Hampshire
      localityName_default            = Southampton
      0.organizationName_default      = Cortex Ltd
      organizationalUnitName_default  = Cortex 
      emailAddress_default            = info@cortex.co.uk
      [ v3_req ]
      basicConstraints = CA:FALSE
      keyUsage = nonRepudiation, digitalSignature, keyEncipherment
      subjectAltName = @alt_names
      [ alt_names ]
      # Specify all DNS and/or IP addresses that clients can use to access the secured resource.
      DNS.1 = MACHINE-NAME 
      DNS.2 = FULLY QUALIFIED MACHINE NAME
      DNS.3 = localhost 
      IP.1 = IP ADDRESS
      IP.2 = 127.0.0.1 
      
    2. Modify the section [alt_names] to include all the required DNS names and IP addresses that clients can use to access the secured resource. Each DNS name or IP address entry must be suffixed with .N where N is the unique index of the DNS name or IP address entry; see below for examples:

      Resource URL Configuration to add
      https://cortex.co.uk/gateway DNS.1 = cortex.co.uk
      https://internal.cortex.co.uk/gateway DNS.2 = internal.cortex.co.uk
      https://10.0.0.0/gateway IP.1 = 10.0.0.0
      https://192.168.1.100/gateway IP.2 = 192.168.1.100
    3. Save the file as san.cnf in the directory created for the certificates above.

    4. In the PowerShell window, run the following command:

      openssl req -new -sha256 -key cortex.key -out cortex.req -extensions v3_req -config san.cnf
      
    5. Press Enter for everything except the Common Name. For this enter Cortex.

    6. Sign the request with a previously generated root CA by running the following command:

      openssl x509 -req -sha256 -in cortex.req -CA cortexCA.pem -CAkey cortexCA.key -CAcreateserial -out cortex.pem -days 3650 -extensions v3_req -extfile san.cnf
      
    7. Package your public and private key in a pkcs12 encrypted file (to install with certmgr on windows) by running the following command:

      openssl pkcs12 -export -inkey cortex.key -in cortex.pem -out cortex.pfx
      
    8. Enter a memorable string as the Export Password when asked, this will be needed when adding the certificate to certmgr.

Import the Certificate

  1. Double click on the cortex.pfx file in the certificates folder to get the certificate imported to the Windows Certificate Store.
  2. Select Local Machine then click Next.
  3. Click Next.
  4. Enter the Export Password which the certificate was generated with then click Next.
  5. Select Place all certificates in the following store.
  6. Click Browse….
  7. Select Personal, click OK then click Next.
  8. Click Finish.

3.1.3.1.8.2 - Port Requirements for the Web Application Server

Information about the ports to be opened when installing the Grafana observability platform.

Port Requirements for the Web Application Server

All the required ports for the Web Application Server that forms part of the Grafana observability platform must be opened on any installed firewall. If any other firewall exists between the Application Servers and the Web Application Server, or Grafana users and the Web Application Server, it will be necessary to configure this selection of rules on it. These ports may be altered if there are any conflicts with other application requirements.

Grafana Observability Platform

Name Description Default Port(s) Protocol Direction
Grafana The port used by the Grafana web application 3000 TCP Inbound
Reverse proxy for Grafana Loki The port used by IIS serving the role of a reverse proxy for Grafana Loki 2100 TCP Inbound

3.1.3.1.8.3 - SSL Best Practices

Information about the recommended security settings for the Grafana observability platform servers.

SSL Best Practices

A collection of registry settings can be applied during installation to guarantee your server is only using the recommended encryption algorithms and TLS protocols:

Type Name Enabled
Ciphers AES 128/128
AES 256/256
Triple DES 168
DES 56/56
NULL
RC2 128/128
RC2 40/128
RC2 56/128
RC4 128/128
RC4 40/128
RC4 56/128
RC4 64/128
Hashes MD5
SHA
SHA256
SHA384
SHA512
KeyExchangeAlgorithms Diffie-Hellman
ECDH
PKCS
Protocols Multi-Protocol Unified Hello
PCT 1.0
SSL 2.0
SSL 3.0
TLS 1.0
TLS 1.1
TLS 1.2
Cipher Suites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA25
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
TLS_DHE_DSS_WITH_AES_256_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_RC4_128_MD5
TLS_RSA_WITH_NULL_SHA256
TLS_RSA_WITH_NULL_SHA
TLS_PSK_WITH_AES_256_GCM_SHA384
TLS_PSK_WITH_AES_128_GCM_SHA256
TLS_PSK_WITH_AES_256_CBC_SHA384
TLS_PSK_WITH_AES_128_CBC_SHA256
TLS_PSK_WITH_NULL_SHA384
TLS_PSK_WITH_NULL_SHA256

3.2 - Set up in the Cloud

Information about setting up observability in the cloud for a Cortex Innovation platform.

3.2.1 - Add Observability to Innovation

Information about setting up an observability platform for Innovation.

3.2.1.1 - Grafana Cloud

Information about adding Grafana Cloud to Innovation, including details about components, supported architectures, prerequisites, installation and configuration instructions.

For instructions on how to set up Grafana and Grafana Loki on-premise see Grafana on-premise.

3.2.1.1.1 - Architecture

Information about the recommended architecture for a Grafana Cloud installation.

Architecture

Components

Component Purpose Required/Optional Server Role
Grafana Web application that provides querying and visualisation of data in the form of dashboards. Required Grafana Cloud managed service
Grafana Loki Log aggregation system designed to store and query logs from applications and infrastructure. Required Grafana Cloud managed service
Promtail An agent which ships the contents of local logs to a Grafana Loki instance. It should be deployed to every machine that has a Microsoft Service Fabric node used by Innovation. Required Application Server

The following architecture requires 1..n Application servers and 1 Grafana Cloud managed service.

Next Steps?

  1. Prerequisites

3.2.1.1.2 - Prerequisites

Information about the prerequisites required on each server type for installation.

Prerequisites

The prerequisites required for each server role (as described in Architecture) are laid out in this guide. These must be considered before undertaking the installation.

Hardware Requirements

The application servers (as described in Architecture) to which Promtail will be added have already been installed as part of the Innovation install process and do not require any hardware modifications for the observability platform installation.

Software Requirements

Server Role Windows Server1 Other Software
Application Server 2019 (x64) Recommended
2016 (x64)
Promtail 2.5.0

Web Browser Requirements

Grafana supports the latest versions of the following browsers:

  • Chrome/Chromium
  • Firefox
  • Safari
  • Microsoft Edge

Additional Application Server Requirements

These requirements apply to each of the Application Servers.

Security Requirements

Installation User

A domain user which is a member of the Local Administrators group on all Application Servers must be available to perform the installation.

Next Steps?

  1. Set up Grafana

  1. Windows Server Standard and Datacenter editions are supported. Filesystem must be NTFS and networking must use IPv4. Linux is not supported, but may be in the future. ↩︎

3.2.1.1.3 - Set up Grafana

Information about setting up Grafana in the cloud.

Set up Grafana

Sign up for Grafana Cloud

  1. Browse to Grafana Labs.

  2. Find and click the link to create free account.

  3. Review the terms and conditions as well as any agreements.

  4. Create your account and follow any account verification steps.

  5. If asked to start a free trial, do so.

  6. On the Let’s create your Grafana Stack dialog:

    • Enter an appropriate Team URL which will be used as a customised link to access the Grafana Cloud.
    • Select the Deployment region which is where the service will be deployed to. This should be preferably close to the High Availability nodes.
  7. Wait for Grafana Cloud to load

Next Steps?

  1. Set up Grafana Loki

3.2.1.1.4 - Set up Grafana Loki

Information about setting up Grafana Loki in the cloud.

Set up Grafana Loki

This guide describes how to set up Grafana Loki in the cloud. Please ensure that the Prerequisites have been completed before starting this installation.

Set up Grafana Loki

  1. Browse to the Team URL created during Sign Up For Grafana Cloud.
  2. Click the Lightening icon Lightening Icon.
  3. Select Integrations and Connections.
  4. In the Add and manage Grafana Cloud integrations and connections click on the Hosted Logs..
  5. In the Choose your usecase section select Send logs from a standalone host.
  6. Enter an Api key name in the Configure promtail to send logs to your Grafana Cloud section and click the Create API key button.
    The key name is used in the Grafana Cloud website to easily identify the key after its creation.
  7. Make a note of the value of the url in the client section of the example configuration. Ignore the instruction to copy and paste the whole content.

Next Steps?

  1. Install Promtail

3.2.1.1.5 - Install Promtail

Information about installing and configuring Promtail on the Application Server(s).

3.2.1.1.5.1 - Install Promtail

Information about installing Promtail on the Application Server(s).

Install Promtail

This guide describes how to install Promtail on the Application Server(s). Please ensure that the Prerequisites have been completed before starting this installation.

Install Promtail

  1. Download Promtail 2.5.0 archive.
  2. Extract content of the downloaded archive to a suitable location, e.g. C:\Promtail.
  3. Download the Promtail Install.zip archive and extract its contents alongside the previously extracted Promtail promtail-windows-amd64.exe. This archive contains the promtail-local-config.yaml configuration file, NSSM (the Non-Sucking Service Manager program) and PowerShell scripts to help manage Promtail as a Windows service.
  4. Run Windows PowerShell as Administrator
  5. Change the location to where all the files were extracted to.
  6. Execute the .\Install-Promtail.ps1 command to install the downloaded promtail-windows-amd64.exe as a service.

Next Steps?

  1. Configure Promtail

3.2.1.1.5.2 - Configure Promtail

Information about configuring Promtail on the Application Server(s).

Configure Promtail

This guide describes how to configure Promtail on the Application Server(s).

Configure Promtail

Set Client URL for Grafana Loki

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.
  2. Replace the Grafana Loki URL template in the clients section with the url value noted down during Set Up Grafana Loki steps. A correct URL should be similar to https://239948:eyJrIjoiaWVjNzE4MmVjOThkNTgxMMQ5MzIyZjdlMjAyYWY4NWJjO1I1OTc4NSIsIm4iOiJUZXN0S2V5IiwiaWQiOjY4Nzk0MX0=@logs-prod-008.grafana.net/api/prom/push.
  3. Save the file.

Set the positions.yaml File Path

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.
  2. Set the filename in the positions section to the location where you want the positions.yaml file to be created on Promtail startup.
  3. Create all the folders of the path specified in the previous step.
  4. Save the file.

Set the Path to the Cortex API Gateway Service Log Files

  1. Open the promtail-local-config.yaml configuration file, which is located in the folder alongside the promtail-windows-amd64.exe file.
  2. Set the __path__ in the static_configs > targets > labels section to the path of the Logs folder specified in the appSettings.json file during installation of the Cortex API Gateway Service, e.g. "C:/ProgramData/Cortex/Cortex API Gateway Service/Logs/*.json".
  3. Save the file.

Start Promtail

  1. Run Windows PowerShell as Administrator.
  2. Change the location to the folder where the promtail-windows-amd64.exe file is located.
  3. Execute the .\Start-Promtail.ps1 command to start the Promtail Windows service.

Next Steps?

  1. Import Dashboards

3.2.1.1.6 - Import Dashboards

Information about setting up Grafana to communicate with the Cloud Grafana Loki as well as importing and configuring the default set of dashboards.

Import Dashboards

This guide describes where to get the default Cortex Innovation Dashboards from and how to import them for use in Grafana Cloud.

Please ensure that the set up for Grafana and Loki have been completed before starting this section.

Download the Cortex Innovation Default Dashboards

  1. Download Grafana.Dashboards.zip archive containing the Cortex Innovation default dashboards.
  2. Extract the content of the downloaded archive to a suitable location.

Create Folder for Dashboards

  1. Log in to Grafana Cloud with a user that has the Admin role.
  2. Hover over the Dashboards icon Dashboards Icon in the side menu, and then click + New folder.
  3. Enter a folder name, e.g. Cortex.
  4. Click Create.

Import Dashboards

  1. Log in to Grafana Cloud with a user that has the Admin role.
  2. Hover over the Dashboards icon Dashboards Icon in the side menu, and then click Import.
  3. Click the Upload JSON file button.
  4. Locate the Flow Execution Requests.json file extracted from the downloaded Grafana.Dashboards.zip.
  5. Select the file and click Open.
  6. Select the folder in Grafana you wish the dashboard to be saved in, e.g. Cortex.
  7. Select your configured Loki data source from the dropdown menu.
  8. Click Import.
  9. Repeat steps 2 - 8 for the Platform Health.json file.

Configure Data Sources

It is necessary to update the Custom Filter inside the dashboards to use the correct data source.

To do this, follow these steps for all default Cortex Innovation dashboards imported:

  1. Log in to Grafana Cloud with a user that has the Admin role.
  2. To open a dashboard:
    1. Hover over the Dashboards icon Dashboards Icon in the side menu, and then click Browse.
    2. Click the folder name that the dashboards were imported to.
    3. Click the Flow Execution Requests dashboard to open it.
  3. Open the Dashboard Settings menu via the cog icon in the top right side of the dashboard.
  4. Click Variables on the left-hand side of the page.
  5. Click Custom Filter in the Variables list.
  6. Select your configured Loki data source in the Options > Data source drop-down menu.
  7. Click Update.
  8. Click the back button on the top left corner of the page to go back to the dashboard.
  9. Click the + icon next to the Custom Filter to confirm that a list of available filter options is visible. If Grafana Loki has not received any logs from Promtail there will be no options available for selection.
  10. Repeat steps 2 - 9 for the Platform Health dashboard.

Next Steps?

  1. Try it Out

3.2.1.1.7 - Try it Out

Information about trying out Grafana Observability Dashboards for the first time.

Try it Out

Check Dashboards are Displaying Data

  1. Open an HTTP client, such as Postman. Make a request with the following format:

    Property Value
    Action POST
    URL For HA installation use:
    https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://load-balancer&#46;domain&#46;com/api/default/default/flows/NewFlow/executions?packageName=NewPackage

    For non-HA installation use:
    https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}
    e.g. https://server&#46;domain&#46;com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage
    Content Type application/json
    Body {}
    Authentication Basic
    Username The value used for ApiGatewayBasicAuthUserName when installing Application Services. See HA Installation script configuration or Non-HA Installation script configuration for the value specified.
    Password The value used for ApiGatewayBasicAuthPwd when installing Application Services (Unencrypted). See HA Installation script configuration or Non-HA Installation script configuration for the value specified.
  2. Once the request has completed, using a web browser, log in to your configured Grafana.

  3. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.

  4. Click the folder name that the dashboards were imported to.

  5. Click the Flow Execution Requests dashboard to open it.

  6. The request made at step 1 should be visible on the dashboard.

  7. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.

  8. Click the folder name that the dashboards were imported to.

  9. Click the Platform Health dashboard to open it.

  10. The request made at step 1 should be visible on the dashboard.

4 - Guides

This section includes all guides for the Cortex Innovation platform.

4.1 - Cortex API Gateway Service

The Cortex API Gateway Service.

4.2 - Cortex Flow Debugger Service

The Cortex Flow Debugger Service.

4.3 - Cortex Flow Execution Service

The Cortex Flow Execution Service.

4.4 - Cortex Gateway

The centralised web-based portal for accessing all user applications and tooling in the Cortex Innovation platform.

4.4.1 - Cortex Gateway Management

Cortex Gateway and Studio Management tools and settings

4.4.1.1 - LDAP Authorisation

Configure RBAC by assining roles to security groups.

4.4.1.2 - LDAP Connection

Connect to an Active Directory using LDAP.

4.4.1.3 - License Consumption

Review current license consumption of flows in master.

4.4.1.4 - Packages

Create and Manage Cortex Innovation Packages

4.4.1.5 - Studio Authorisation

Assign access rights to flows based on security groups.

4.4.1.6 - Studio Export

Create Cortex Studio Packages by exporting flows.

4.4.1.7 - Studio Hierarchy

Manage the location of flows in the Flow Hierarchy.

4.4.1.8 - Studio Import

Import Cortex Studio Packages.

4.4.1.9 - Version Control

High level view of flows out of sync with master. Allow for mass Commit or Get Master

4.4.2 - Help

System level help

4.4.2.1 - Release Notes

Release notes for all currently available Cortex Versions.

4.5 - Cortex Studio

The web-based, low-code, integrated development environment (IDE) for creating, editing, debugging, testing and managing flows that define the logic and actions required to capture and automate simple user tasks through to complex business or IT processes.

4.5.1 - Cortex Studio - East Panel (TBC)

Eastern panel for Property Editor, Execution Viewer and Exceptions

Summary

Property Editor

Add Variables button

Show/Hide Advanced Properties button

Help button

Execution Viewer

Variables Viewer

Variable Details Viewer

Load Value Button

Exceptions Viewer

Settings Editor

Inputs Property

Remarks

Known Limitations

See Also

4.5.2 - Cortex Studio - Main Display Area

The Main Display Area for developing and managing a flow

Summary

Main Toolbar

Undo

TODO:

  • What happens when an undo action is taken
  • What can be undone
  • Keyboard Shortcuts?

Redo

TODO:

  • What happens when an redo action is taken
  • What can be redone
  • Keyboard Shortcuts?

Start an execution

TODO:

  • Should this be called ‘starting an execution’ or ‘debugging an execution’
  • Start execution via API or Studio
    • describe the steps of starting from API (API call is made to Gateway, Authentication and Authorisation is performed, Gateway proxied called to debugger service, etc)
    • describe the steps of starting from Studio (User clicks button, call is made to Gateway, Authentication and Authorisation is performed, Gateway proxied called to debugger service, etc)
  • Image of button and token after button was pressed
  • Executions are private and only displayed to the user that requested them (Check this is true, look at the APIs).
  • link debugging in this page to glossary
  • link ‘what is an execution.md’ debugging/production to glossary
  • Providing input variables (API or Studio)
    • literals and expression
  • Retrieving Output variables (API or Studio)

Break On Exception

TODO

Edit and Continue an Execution

Workspaces

Blocks

Breakpoints

Executions

Executions are represented by tokens on a workspace.

Set Next Block to Execute

Workspace Toolbar

Remarks

Known Limitations

See Also

4.5.3 - Cortex Studio - Navigation

How to navigate between and in flows

Summary

Quick Navigation

Swimlane Management

Remarks

Known Limitations

See Also

4.5.4 - Cortex Studio - Package Management (TBC)

Package Management

Summary

Remarks

Known Limitations

See Also

4.5.5 - Cortex Studio - Palettes

Block palette information

4.5.6 - Cortex Studio - South Panel (TBC)

Southern panel for Executions, Messages, and Variables

Summary

Executions Grid

Pausing an Execution

Stepping an Execution

Continuing an Execution

Stopping an Execution

Variables Grid

TODO: Add Screenshot of Grid

Creating Variables

TODO: Screenshots, How to create

Viewing Variables

TODO: Screenshots, Searching/Filtering

Modifying Variables

TODO: Screenshots, How to modify

Changing a Variable’s Scope

TODO: Screenshots, how to modify scope

  1. Find the variable in the [Variable Grid][]
  2. Double-click the Scope to load a dropdown menu
  3. Select the desired workspace

If the variable does not appear in the grid, the most likely reason is the variable is not in scope of the workspace currently in focus. To resolve this, either select the appropriate workspace, or change the Scope filter on the [Variable Grid][] to All.

Deleting Variables

TODO: Screenshots, How to delete

Messages Grid

Remarks

Known Limitations

See Also

4.5.7 - Debugging

Summary

Property Viewer

Remarks

Known Limitations

See Also

4.5.8 - Cortex Studio - Expression Editor

A guide on how to use the Expression Editor

Summary

TODO: What is used for, etc.

Snippets

TODO: How to Access, Whats Available, etc

Tools

TODO: Full Screen, Find and Replace, Command Menu, Replace All (Ctrl F2), etc

Example Expressions

TODO: Variable, Object Construct (Complex/Collection), String Concatenation/Interpolation, Arithmetics, etc

Remarks

Known Limitations

See Also

TODO

4.5.9 - Cortex Studio - Literal Editor

A guide on how to use the Literal Editor

Summary

TODO: What is used for, etc.

Selecting a Literal Type

TODO: Searching/Filtering

Remarks

Known Limitations

See Also

TODO

4.5.10 - Cortex Studio - Variable Editor

A guide on how to use the Variable Editor

Summary

TODO: What is used for, etc.

Selecting Variables

TODO: Searching/Filtering TODO: Complex/Collection variable referencing

Creating Variables

TODO: Create variable from property, create all undefined variables

Remarks

Known Limitations

See Also

TODO

5 - Tutorials

This section includes all tutorials for the Cortex Innovation platform.

5.1 - Installation

This section includes tutorials about installing the Cortex Innovation platform.

5.2 - Setup

This section includes tutorials about post-installation setup of the Cortex Innovation platform.

5.3 - Development

This section includes tutorials about developing automation using the Cortex Innovation platform.

Development

This section includes tutorials about developing automation using the Cortex Innovation platform.

Signing in and out of Gateway

Shows how to sign in and out of Cortex Gateway.

Overview of Gateway

Shows a high-level overview of Cortex Gateway.

Creating groups and moving flows

Shows how to create new groups, and move existing flows between groups.

Creating and interacting with flows

Shows how to create a flow, and provides an overview of commonly used features of the flow editor.

Interacting with blocks

Shows how to add, connect, copy, cut, paste, and delete blocks.

Configuring variables

Shows how to create and configure variables.

Configuring blocks

Shows how to configure blocks using the Properties Editor.

Handling exceptions at the block level

Shows how to handle exceptions at the block level.

Handling exceptions at the workspace level

Shows how to handle exceptions at the workspace level.

Handling exceptions at the flow level

Shows how to handle exceptions at the flow level.

Throwing exceptions

Shows how to throw an exception within a flow.

Debugging a flow

Shows how to start debugging a flow.

Adding and removing breakpoints

Shows how to add and remove breakpoints when debugging a flow.

Editing a flow whilst debugging

Shows how to edit a flow whilst debugging, including fixing a runtime exception.

Interacting with version control

Shows how to save, commit, get master, and compare versions of a flow.

Interacting with version control (multiple flows)

Shows how to perform commit or get master of multiple flows.

Starting a published flow

Shows how to start a flow, in the default package, via the API Gateway Service using an HTTP request.

Starting a published flow (specific package)

Shows how to start a flow, in a specific package, via the API Gateway Service using an HTTP request.

Configuring input and output variables

Shows how to configure the input and output variables of a flow.

5.4 - Administration

This section includes tutorials about administering the Cortex Innovation platform.

Administration

This section includes tutorials about administering the Cortex Innovation platform.

Managing role-based access control

Shows how to manage role-based access control within Gateway, including assigning access and flow permissions.

Exporting flows

Shows how to export a set of flows as a .studiopkg file.

Importing flows

Shows how to import a set of flows from a .studiopkg file.

Creating packages

Shows how to create a release package containing all the flows required for your self-contained automation solution.

Publishing packages

Shows how to publish a release package into your runtime environment.

Managing package versions

Shows how to create new versions of a release package, including adding flows, updating flow versions, and removing flows.

Setting default packages

Shows how to set the default package and the default version of each package.

5.5 - Troubleshooting

This section includes tutorials about troubleshooting the Cortex Innovation platform.

Troubleshooting

This section includes tutorials about troubleshooting the Cortex Innovation platform.

Errors when starting published flows

When making requests to start published flows, you may encounter errors. The videos below will show you how to fix them.

FlowNotFound

InvalidInputVariables

6 - Reference

This section includes all reference documentation for the Cortex Innovation platform.

6.1 - Concepts

This section includes all reference documentation for concepts required to use Cortex Innovation.

6.1.1 - Fundamentals

Fundamental concepts when working with Cortex Innovation.

6.1.1.1 - Flows

Information regarding what a flow is, how to call other flows and handling exceptions within a flow.

6.1.1.1.1 - What is a Flow?

Information regarding the anatomy of a flow, starting flows, grouping logic within a flow, and handling exceptions within a flow.

What is a Flow?

Summary

A flow is an object in Cortex Studio that contains the logic and actions (in the form of blocks and workspaces) that is able to be executed on a Cortex Innovation platform.

Anatomy of a Flow

Example Flow
Example Flow
  • Start Flow block
    • Identifies where the flow execution will start
    • Automatically created when the flow is created
    • Cannot be deleted
    • See Start Flow block
  • Action blocks
    • Performs a specific action
    • Icon on block indicates the nature of the action
    • See Blocks
  • Decision block
  • Workspace blocks
    • Contains grouped flow logic
    • The turndown on the top-right of the icon indicates it contains a workspace, which can be opened by double-clicking the icon
    • See Workspace block
  • End Flow block
  • Handle Flow Exception block
  • Flow Variable Store
    • This is deprecated in favour of the Variables Grid
    • The Variables Grid can be opened by double-clicking the icon, the scope will be set to Defined (Selected Workspace)
    • Cannot be deleted
  • Workspace

Grouping Logic within a Flow

All the logic of a flow can exist on the Top-Level Workspace, however, this can quickly become difficult to maintain and understand as the numbers of blocks increase. Blocks can be grouped into workspaces in order to reduce the complexity and make the flow easier to maintain.

A Workspace block can opened by double clicking it, showing its workspace canvas and the logic inside; this could include blocks for executing specific functions or other workspaces to help separate the logic of the flow further.

For further information about workspaces, see Workspaces.

Starting a Flow Execution

A flow execution may be started by:

  • Debugging a flow in Cortex Studio
  • Triggering it by making an HTTP request from an external source (e.g. a web application or web hooks)
  • Triggering it using the Run Flow block
  • Triggering it using predefined events (future) (e.g. on receipt of an email)
  • Scheduling it to execute at predetermined times

Exceptions within a Flow

Flows support hierarchical exception handling at any level within the flow.

Exceptions can be handled:

Remarks

Known Limitations

Cannot have a Handle Workspace Exception block on the flow’s Top-Level Workspace

Currently, it is not possible to have a Handle Workspace Exception block on the Top-Level Workspace of a flow. In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.1.2 - Calling Other Flows

Information regarding calling, and passing data to, other flows.

Calling Other Flows

Summary

A flow may trigger the execution of another flow.

Calling Another Flow

A flow can be called from another flow in the following ways:

  • Using the Run Flow block to trigger the execution of another flow directly
  • Using the Execute HTTP Request block to trigger a flow through the API Gateway service (this should only be used to call flows published in a separate Cortex Innovation platform)

Input Variables

Sometimes flows require data to be passed to them through the use of input variables (e.g. a flow used to log errors may require a file path for where the logs are saved).

Input variables can be passed into flows in the following ways:

Output Variables

Sometimes flows may return data through the use of output variables (e.g. a flow used to interact with a database may return its results).

Output variables are returned to the calling flow in the following ways:

Remarks

Known Limitations

Flows can only be Called Synchronously

Currently it is only possible to call other flows synchronously; this means the calling flow will wait for the called flow to complete its execution before continuing.

In the future it will be possible to call flows asynchronously; this means the calling flow will continue after the called flow starts its execution without waiting for the called flow to complete.

See Also

External Documentation

None

6.1.1.1.3 - Handling Exceptions within a Flow

Information regarding handling exceptions at different levels within a flow.

Handling Exceptions within a Flow

Summary

Exceptions within a flow can be handled at the following levels:

The Handle Flow Exception block, which is located on the top-level workspace, handles any exceptions that are not handled at the block or workspace level.

For more information, see Handling Exceptions.

Remarks

Flow cannot be re-entered from the Handle Flow Exception Workspace

Is it not possible to re-enter a flow once a flow execution enters the workspace of the Handle Flow Exception block.

Known Limitations

None

See Also

External Documentation

None

6.1.1.2 - Workspaces

Information regarding what a workspace is, workspace scopes, and handling exceptions within a workspace.

6.1.1.2.1 - What is a Workspace?

Information regarding the anatomy of a workspace, nested workspaces, variable scope, and handling exceptions within a workspace.

What is a Workspace?

Summary

A workspace is used to group logic and actions within a flow, in order to reduce the complexity and make the flow easier to maintain.

Anatomy of a Workspace

Top-Level Workspace

A flow can only contain one Top-Level Workspace, which acts as the entry point for the flow execution.

Example Flow
Example Top-Level Workspace
  • Start Flow block
    • Identifies where the flow execution will start
    • Automatically created when the flow is created
    • Cannot be deleted
    • See Start Flow block
  • Action blocks
    • Performs a specific action
    • Icon on block indicates the nature of the action
    • See Blocks
  • Decision block
  • Workspace blocks
    • Contains grouped flow logic
    • The turndown on the top-right of the icon indicates it contains a workspace, which can be opened by double-clicking the icon
    • See Workspace block
  • End Flow block
  • Handle Flow Exception block
    • Handles flow level exceptions, thrown during the flow execution
    • Automatically created when the flow is created
    • The turndown on the top-right of the icon indicates it contains a workspace, which can be opened by double-clicking the icon
    • Cannot be deleted
    • See Handle Flow Exception block
  • Flow Variable Store
    • This is deprecated in favour of the Variables Grid
    • The Variables Grid can be opened by double-clicking the icon, the scope will be set to Defined (Selected Workspace)
    • Cannot be deleted
  • Workspace
    • The Top-Level Workspace within the flow
    • Canvas on which blocks are placed and connected to create the flow logic

Other Workspaces

A flow can contain any number of other workspaces that are not the Top-Level Workspace, these act as a means to grouping logic and actions to reduce the complexity and make the flow easier to maintain.

Example Flow
Example Workspace
  • Start Workspace block
    • Identifies where the flow execution will start when the workspace is executed
    • Automatically created when the workspace is created
    • Cannot be deleted
    • See Start Workspace block
  • Action blocks
    • Performs a specific action
    • Icon on block indicates the nature of the action
    • See Blocks
  • End Workspace block
    • Ends the execution of the workspace
    • Automatically created when the workspace is created
    • See End Workspace block
  • End Flow block
  • Handle Workspace Exception block
  • Workspace Variable Store
    • This is deprecated in favour of the Variables Grid
    • The Variables Grid can be opened by double-clicking the icon, the scope will be set to Defined (Selected Workspace)
    • Cannot be deleted
  • Workspace
    • A nested workspace within the flow
    • Canvas on which blocks are placed and connected to create the workspace logic

Nested Workspaces

All the logic of a flow can exist on the Top-Level Workspace, however, this can quickly become difficult to maintain and understand as the numbers of blocks increase. Blocks can be grouped into workspaces in order to reduce the complexity and make the flow easier to maintain.

A Workspace block can opened by double clicking it, showing its workspace canvas and the logic inside; this could include blocks for executing specific functions or other workspaces to help separate the logic of the flow further.

When an End Workspace block is executed, the flow execution returns to the parent workspace. However, when an End Flow block is executed the flow execution will end.

A nested workspace has access to any variables defined within its scope, or any direct ancestors scope.

Exceptions within a Workspace

Workspaces support hierarchical exception handling at any level within the workspace.

Exceptions can be handled:

A Top-Level Workspace can also handle exceptions at the flow level; for further information, see Handling Exceptions within a Flow

Remarks

Known Limitations

Cannot have a Handle Workspace Exception block on the flow’s Top-Level Workspace

Currently, it is not possible to have a Handle Workspace Exception block on the Top-Level Workspace of a flow. In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.2.2 - Handling Exceptions within a Workspace

Information regarding handling exceptions at different levels within a workspace.

Handling Exceptions within a Workspace

Summary

Exceptions within a workspace can be handled at the following levels:

A single Handle Workspace Exception block may be placed on a workspace to handle any exceptions that are not handled at the block level.

For more information, see Handling Exceptions.

Remarks

Known Limitations

Handle Workspace Exception block can only be used once per execution of a Workspace

The Handle Workspace Exception block will only handle the first unhandled exception within its workspace. Subsequent unhandled exceptions are passed to the next relevant exception handling block. In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.3 - Blocks

Information regarding what a block is, block properties and their editors, and handling exceptions thrown by a block.

6.1.1.3.1 - What is a Block?

Information regarding the anatomy of a block, types of blocks and their appearance, connecting blocks, and block properties.

What is a Block?

Summary

A block is used to perform an action, or branch based on a condition within a flow.

Blocks are organised into palettes based on the type of object they operate on or the system they interact with (e.g. Blocks that operate on Lists can be found in the Lists palette). Blocks can be dragged from a palette on to a workspace, and connected to one another to create the logic of the flow.

Anatomy of a Block

There are five types of block, each type has its own image, connection ports and properties:

Flow Control Blocks

Flow Control blocks are used to start or end a flow or workspace.

Block Image

Flow Control Blocks

  • Flow Control blocks are square shaped
  • Flow Control blocks are smaller than Action Blocks
  • Flow Control blocks have a pale blue background

Connection Ports

Flow Control Blocks that start a flow or workspace have the following connection ports:

  • One output port located on the bottom of the block

An execution moves to the input port of the block connected to the output port.

Flow Control Blocks that end a flow or workspace have the following connection ports:

  • One input port located on the top of the block

An execution passes through the input port, and ends the flow or workspace depending on the logic of the block.

Action Blocks

Action blocks are used to perform an action within a flow. They can operate on an object or interact with a system.

Exceptions thrown by Action blocks can be handled by connecting a Handle Block Exception block to the red output port.

Block Image

Action Blocks

  • The icon of the Action block shows what object or system it interacts with
  • The icon in the bottom right of the Action block provides further information into what type of action or interaction it will take
  • Action blocks are square shaped
  • Action blocks have a pale blue background

Connection Ports

Action blocks have the following connection ports:

  • One input port located on the top of the block
  • One output port located on the bottom of the block
  • One red exception output port located on the right of the block

An execution passes through the input port, executes the block, and if no exception occurs, moves to the input port of the block connected to the output port; if an exception occurs the execution moves to the exception input port of the exception handling block connected to the exception output port.

Decision Blocks

Decision blocks are used to branch within a flow based on a condition.

Block Image

Decision Blocks

  • The icon of the Decision block shows what object or system it interacts with
  • Decision blocks are diamond shaped
  • Decision blocks have a pale blue background

Connection Ports

Decision blocks have the following connection ports:

  • One input port located on the top of the block
  • One output port located on the right the block
  • One output port located on the bottom of the block

An execution passes through the input port, executes the block, and based on the result of the execution moves to the input port of the block connected to the correct output port.

Exception Handling Blocks

Exception Handling blocks are used to handle exceptions thrown within a flow.

Exceptions can be handled at different levels within a flow; at the block level, the workspace level, and the flow level. For more information see Handling Exceptions.

Block Image

Exception Handling Blocks

  • Exception Handling blocks have a pink background

Connection Ports

Handle Block Exception blocks have the following connection ports:

  • One red exception input port located on the left of the block
  • One red exception output port located on the right of the block if they can be chained
  • One output port located on the bottom of the block

An execution passes through the exception input port, executes the block, and if the exception can be handled, moves to the input port of the block connected to the output port; if an exception cannot be handled the execution moves to the exception input port of the exception handling block connected to the exception output port, for more information see Chaining Block Exception Handling Blocks.

Handle Workspace Exception blocks have the following connection ports:

  • One output port located on the bottom of the block

Handle Flow Exception blocks have no connection ports.

Workspace Blocks

Workspace blocks are used to group logic and actions within a flow in order to reduce the complexity and make the flow easier to maintain. For more information see Workspaces.

Unhandled exceptions thrown within a workspace can be handled by connecting a Handle Block Exception block to the red output port of the Workspace block.

Block Image

Workspace Blocks

  • Workspace blocks are rectangle shaped
  • Workspace blocks are larger than Action Blocks
  • Workspace blocks have a pale blue background

Connection Ports

Workspace Blocks have the following connection ports:

  • One input port located on the top of the block
  • One output port located on the bottom of the block
  • One red exception output port located on the right of the block

An execution passes through the input port and executes the workspace block, and if no unhandled exception occurs, moves to the input port of the block connected to the output port; if an unhandled exception occurs the execution moves to the exception input port of the exception handling block connected to the exception output port.

Block Properties

Blocks are configured using Block Properties. Properties pass data to the block which is then used to perform an action, or branch based on a condition within a flow.

There are three types of block properties:

Most blocks share Common Properties such as a description for the block. Some blocks have Advanced Properties that do not normally need to be configured but allow for more advanced scenarios.

For further information, see Block Properties.

Block Connections

Block connections help determine the order blocks will be executed in a flow, an execution moves through the flow sequentially

An execution moves from one connected block to another, depending on the logic of the block. Blocks can be connected to each other through the use of connection ports.

There are four types of connections ports

  • Input Ports - act as the entry point of a block, output ports from one or more other blocks can be connected to an input port
  • Output Ports - act as the exit point of a block, output ports can only be connected to an input port of one other block
  • Exception Input Ports - act as the entry point of an exception handling block, exception output ports from one or more other blocks can be connected to an exception input port
  • Exception Output Ports - act as the exit point of a block when an exception is thrown, exception output ports can only be connected to an exception input port of one exception handling block

Exceptions within a Block

Exceptions thrown within the execution of a block can be handled by connecting a Handle Block Exception block to the red output port. If there is no Handle Block Exception block that can handle the exception then it will be passed to the workspace level to be handled.

For further information, see Handling Exceptions within a Block.

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.3.2 - Block Properties

Information regarding what a block property is, the types of properties, the different property editors, and block properties that are common or advanced.

6.1.1.3.2.1 - What is a Block Property?

Information regarding the anatomy of block properties, types of property and their appearance, and configuring properties using the available property editors.

What is a Block Property?

Summary

Blocks are configured using Block Properties. Properties pass data to the block which is then used to perform an action, or branch based on a condition within a flow.

Anatomy of a Block Property

There are three types of block property, each type can be configured using one of its supported editors:

Input Properties

Input properties are used to provide values to a block. These properties are used in the block’s execution (e.g. a block to send emails would have input properties for specifying things like the sender, recipients, summary, body, attachments etc.).

Supported Editors

Input properties can be configured using the following editors:

Supported Editors

The icons used for Input properties are dark blue to distinguish them from Output Properties or InputOutput Properties.

Output Properties

Output properties are used to save values from a block. These properties will saved to a variable during the block’s execution.

Values from Output properties can be discarded, this means they will not be saved to any variable.

Supported Editors

Output properties can be configured using the following editors:

Supported Editors

The icon used for Output properties are light blue to distinguish them from Input Properties.

Discarding Outputs

Output values can be discarded, instead of saving them to a variable.

Common reasons for discarding include:

To discard an output value, the Output property should use the built-in ($)_ variable.

Supported Editors

InputOutput Properties

InputOutput properties are used to provide values to a block. These properties are used, updated and saved back to a variable during the block’s execution.

Supported Editors

InputOutput properties can be configured using the following editors:

Supported Editors

The icons used for InputOutput properties are light blue to distinguish them from Input Properties.

Remarks

Known Limitations

The Literal Editor is not Supported for all Input Properties

Currently, not all Data Types support the use of the Literal Editor, such as:

Information regarding which editors are supported for a Data Type can be found in the “Remarks” section under “Property Editor Support” in the relevant documentation for that Data Type.

In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.3.2.2 - Property Editors

Information regarding the Literal, Variable, and Expression Editors.

6.1.1.3.2.2.1 - Literal Editor

Information regarding using the Literal Editor.

Literal Editor

Summary

TODO

Available Types

TODO:

  • The literal editor will have one or more available types, these types will be either Complex or Basic Types
  • The types available to the literal editor are restricted by the block property.
  • It is possible to switch the type of the literal editor to any available type.

Basic Types

TODO:

  • Single Editor

TODO: Image of basic literal editor

Complex Types

TODO:

  • Nested editors within a complex type
  • List and Dictionary Editors

TODO: Image of complex literal editor

Switching Type

TODO:

  • What are DataType and CurrentType?
  • An editor can be switched using the type selector (accessed by clicking on the property name)

TODO: Image of type selector

Remarks

Known Limitations

TODO:

  • There is no literal support for Collection Types or types that have constructors with no parameters.

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.1.3.2.2.2 - Variable Editor

Information regarding using the Variable Editor.

Variable Editor

Summary

TODO

Using Variables

TODO:

  • You can use any available variable.
  • Available variables are restricted by the scope of the currently selected block
  • All available variables will be shown when the variable editor is empty; typing in the editor will filter the available variables with those that match (contains text) on either the variable name or scope

TODO: Image of using a variable

TODO: Image of selecting available variables

Scoped Variables

TODO:

  • Available variables are scoped by the workspace of the block selected
  • Can see variables of the same name that are on accessible scopes
  • Link to known limitation. If there are two or more variables with the same name, the variable with the closest scope will be always used even if another is selected

TODO: Image of scoped variables (different names and same names)

Accessing Variable Properties or Indexes

TODO:

  • Properties and indexes can be accessed from the Variable editor
  • Translation error shown in messages viewer when using properties or indexes incorrectly for variable that is not dynamic

TODO: Image of accessing variable property and index

Missing Variables

TODO:

  • If a variable does not exist, then a orange border will be shown around the Variable editor
  • It is possible to create a new variable from a missing one using the variable editor

TODO: Image of orange border for missing variables

Creating Variables

TODO:

  • If a variable does not already exist, the variable editor can be used to create a new one at the current scope
  • If the variable name is invalid (C# identifier naming rules) then there will be no option to create a new variable

TODO: Image of option to create a new variable

Renaming Variables

TODO:

  • If a variable editor already contains a reference to a variable that exists, typing the name of a non-existent variable will provide the option to rename the previously selected variable (and all references to it within the flow) to the new variable name
  • If the variable name is invalid (C# identifier naming rules) then there will be no option to rename the variable
  • Renaming a variable does not include any index or method expressions (e.g. renaming to ($)NewVar.ToString() will rename the selected variable to ($)NewVar)

TODO: Image of option to rename a variable

Remarks

Known Limitations

TODO:

  • If there are two or more variables with the same name, the variable with the closest scope will be always used even if another is selected
  • Currently, available variables are not restricted based on the type of the variable and if that is valid for the selected property

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.1.3.2.2.3 - Expression Editor

Information regarding using the Expression Editor to create literal values, expressions, or use variables.

Expression Editor

Summary

The Expression Editor is the most powerful property editor and can accept literal values, expressions, and variables.

Empty Expression

Literal Values

A literal is an explicit value that is not calculated during the execution of the flow. A literal can be any of the following data types:

String literal

String literal

String literals are surrounded by double quotes. For example:

"Example String"

The example above becomes:

Example String

Double quotes that form part of the string, along with the back-slash character and any unicode character codes or hexadecimal character codes, must be escaped by a back-slash character. For example:

"He said \"Come here\x0021\""

The example above becomes:

He said "Come here!"

For verbatim string literals, double quotes that form part of the string literal must be duplicated to give a single double quote character. For example:

@"He said ""Come here!"""

The example above becomes:

He said "Come here!"

For interpolated strings, variables or expressions are surrounded by single curly braces. For example:

$"He said \"Come here {($)Name}!\""

For further information on interpolated strings using variables or expressions see String expressions

In the case of interpolated verbatim string literals, double curly braces are not interpreted literally; they produce a single curly brace character. For example:

$@"This is a single square brace ""["", and this is a single curly brace ""{{"""

The example above becomes:

This is a single square brace "[", and this is a single curly brace "{"

For further information, see String Literals

Char literal

Char literal

Char literals are single characters; they are surrounded by single quotes. For example:

'A'
'\u0041'

The example above becomes:

'A'
'A'

For further information, Char Literals

Int32 literal

Int32 literal

If an integer literal value is greater than or equal to Int32.MinValue or less than or equal to Int32.MaxValue, then it will be of type Int32

1234

If an integer literal value is less than Int32.MinValue or greater than Int32.MaxValue, then it will be of type Int64.

For further information, see Integer Literals.

Int64 literal

Int64 literal

If an integer literal value is less than Int32.MinValue or greater than Int32.MaxValue, then it will be of type Int64.

2147483648
1234l
1234L

For further information, see Integer Literals.

Double literal

Double literal

By default, floating point literals are of type Double.

1234.456

The suffix d or D can used to create a floating point literal of type Double, but is unnecessary.

1234.456d
1234.456D

For further information, see Real Literals.

Single literal

Single literal

If it is necessary to create an floating point literal of type Single with a value greater than or equal to Single.MinValue or less than or equal to Single.MaxValue, then the floating point literal must be suffixed by the character f or F. For example:

1234.456f
1234.456F

For further information, see Real Literals.

Boolean literal

Boolean literal

A Boolean literal represents a truth-value of either true or false.

true or false

For further information, see Boolean Literals.

Object literal

Currently, creating an object using literal syntax is not supported.

Dictionary literal

Currently, creating a dictionary using literal syntax is not supported; any attempt to make a dictionary using literal syntax will create a Structure instead.

Structure literal

Structure literal

Structures are a special type of Dictionary that always have string keys.

{
  "Name1" : "",
  "Name2" : 1,
  "Name3" : true,
  "Name4" : {},
  "Name5" : [],
  "Name6" : null
}

They differ from a Dictionary in the syntax used for accessing the item:

List literal

List literal

A List is an object that consists of a number of ordered items that can be of any data type.

[
  "Example String",
  1,
  true,
  {},
  [],
  null
]

Lists may be heterogeneous, where the items may be of different data types, or homogeneous, when the items are all of the same data type.

Variables

Variables

Variables are named containers for storing values of any data type; a variable’s value can be read, updated, replaced, or removed using variable syntax; where the variable name is prefixed with ($) (e.g. ($)VariableName).

Variables can be used within expressions.

Expressions

An expression is a combination of operands (i.e. variables, literals, calls to methods and properties exposed on data types) and operators (i.e. =, +, -, *, /) that will be evaluated when the flow execution reaches the block.

Expressions use the syntax of the C# programming language.

Types of expressions:

Arithmetic expressions

Arithmetic expressions

The following operators perform arithmetic operations with operands that have numeric values.

In the examples below assume:

  • ($)Int1 has been set to 6
  • ($)Int2 has been set to 3
Expression Result Notes
($)Int1 + ($)Int2 9 Add
($)Int1 - ($)Int2 3 Subtract
($)Int1 * ($)Int2 18 Multiply
($)Int1 / ($)Int2 2 Divide
($)Int1 % ($)Int2 0 Remainder

For further information, see Arithmetic Operators.

Boolean expressions

Boolean expressions

The following operators perform logical operations with operands that have boolean values.

In the examples below assume:

  • ($)Bool1 has been set to false
  • ($)Bool2 has been set to true
Expression Result Notes
($)Bool1 && ($)Bool2 false AND
($)Bool2 || ($)Bool1 true OR
($)Bool1 ^ ($)Bool2 true XOR
!($)Bool1 true NOT

For further information, see Boolean Logical Operators.

Comparison expressions

Comparison expressions

The following operators perform comparison operations with operands.

In the examples below assume:

  • ($)Int1 has been set to 1
  • ($)Int2 has been set to 2
Expression Result Notes
($)Int1 == ($)Int2 false Equal
($)Int1 != ($)Int2 true Not Equal
($)Int1 > ($)Int2 false Greater Than
($)Int1 >= ($)Int2 false Greater Than or Equal
($)Int1 < ($)Int2 true Less Than
($)Int1 <= ($)Int2 true Less Than or Equal

For further information, see Equality Operators, Comparison Operators, and Object Equality.

String expressions

There are three types of string expressions:

If a data type is used in a string expression that is not a String, then it will be implicitly cast to a String as part of the expression.

In all of the examples below assume:

  • ($)String1 has been set to "hello"
  • ($)String2 has been set to "world"
  • ($)Int has been set to 1234

Concatenated Strings

Concatenated Strings

Concatenation is the process of appending one String to the end of another String. You concatenate strings by using the + operator.

Expression Result Notes
($)String1 + " " + ($)String2 "hello world"
($)String1 + " " + ($)Int "hello 1234" The variable ($)Int is implicitly cast to a String as part of the expression

For further information, see String concatenation.

Interpolated Strings

Interpolated Strings

Interpolation is the process of inserting expressions and variables into a String. An interpolated string is declared by prefixing the string with the $ character.

Expression Result Notes
$"{($)String1} {($)String2}" "hello world"
$"{($)String1} {($)Int}" "hello 1234" The variable ($)Int is implicitly cast to a String as part of the expression
$"{($)String1} {($)Int + 1}" "hello 1235" The expression ($)Int + 1 is evaluated and the result is implicitly cast to a String as part of the expression

For further information, see String interpolation.

Verbatim Strings

Verbatim Strings

A verbatim string identifies that characters within the string should be processed literally, and do not need to be escaped. However, the following exceptions apply:

  • In both Verbatim and Interpolated Verbatim strings the double quote character " is escaped by prefixing it with another double quote character
  • In Interpolated Verbatim strings the curly brace characters { and } are escaped by prefixing them with the same curly brace character
Expression Result Notes
@"c:\programs\file.txt" "c:\\programs\\file.txt"
@"They said ""Hello!""" "They said \"Hello!\"" The " character is escaped
$@"{{ Some Text }}" "{ Some Text }" Interpolated Verbatim String, The curly brace characters are escaped
$@"c:\programs\{($)String1}.txt" "c:\\programs\\hello.txt" Interpolated Verbatim String

For further information, see Verbatim string literals and Verbatim String Interpolation.

Dictionary expressions

Dictionaries can be created using Constructor expressions and their items can be accessed using Index expressions.

For examples of creating Dictionaries using constructor expressions, see Create a Dictionary<TKey, TItem>.

Structure expressions

Structures can be created using Constructor expressions and their items can be accessed using Property expressions (keys must follow C# identifier naming rules) or Index expressions (keys do not need to follow C# identifier naming rules).

For examples of creating Structures using constructor expressions, see Create a Structure.

List expressions

Lists can be created using Constructor expressions and their items can be accessed using Index expressions.

For examples of creating Lists using constructor expressions, see Create a List<TItem>.

Constructor expressions

Constructor expressions

Constructors can be used to create a new instance of a Data Type. A Data Type can have multiple constructors, each with different parameters that are used to create the new instance.

Methods on how to create a new instance of a Data Type can be found in the relevant documentation for that Data Type; information regarding how to create a new Data Type using a constructor can be found in the “Remarks” section under “Create a/an <DataType>” (where <DataType> is replaced by the type’s name).

The following examples show two ways a DateTimeOffset can be created using a constructor:

In the examples below assume the variable ($)Year has been set to 2022.

Expression Result Notes
new DateTimeOffset() 0001-01-01T00:00:00+00:00 12AM 1st January 0001 with 0 hour UTC offset, the default for a new DateTimeOffset with no parameters
new DateTimeOffset(($)Year, 7, 1, 14, 0, 0, 0, new TimeSpan(1, 0, 0)) 2022-07-01T14:00:00+01:00 2PM 1st July 2022 with 1 hour UTC offset

Note that some Data Types should be created via literal values instead of their constructors, these include:

For further information, see Constructors.

Method expressions

Method expressions

Methods can be used to execute specific functionality. The methods accessible are defined by the Data Type, and information regarding methods can be found in the relevant documentation for that Data Type.

Methods can have parameters passed into them that are then used to execute the functionality, not all methods have parameters. The same method can be defined multiple times, each with different sets of parameters.

In the examples below assume the variable ($)Int has been set to 1.

Expression Result Notes
TimePeriod.FromSeconds(60) {"Years": 0, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 1, "Seconds": 0, "Milliseconds": 0} Method with parameters
($)Int.ToString() "1" Method without parameters
($)Int.ToString("P0") "100%" The ToString() method can take parameters in order to format the result. In this case 1 was converted into a percent with zero decimal places

For further information, see Methods.

Property expressions

Property expressions

Properties can be used to read data from and/or write data to a Data Type. The properties accessible are defined by the Data Type, and information regarding properties can be found in the relevant documentation for that Data Type.

Properties can be read-write, read-only, or write-only (extremely rare) depending on the access specified by the Data Type.

Whilst Structures are Collections, they also allow for their keys to be accessed as properties.

In the examples below assume:

  • ($)TimePeriod has been set to {"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}
  • ($)Structure has been set to {"FirstKey": 1, "SecondKey": 2}
Expression Result Notes
DateTimeOffset.UtcNow 2022-07-01T13:00:00.0000000+00:00 Read-only property, this only works in Input Properties
($)TimePeriod.Years 1 Read-write property, this can be used in Input, Output, and InputOutput Properties. The result column shows reading the property; writing to the property can be achieved by using any Output Property.
($)Structure.FirstKey 1 Read-write property, this can be used in Input, Output, and InputOutput Properties. The result column shows reading the property; writing to the property can be achieved by using any Output Property.

For further information, see Properties.

Enum expressions

Enum expressions

Enum data types have a defined set of values, where each value has an associated String name and Int32 value. Information regarding values can be found in the relevant documentation for that Data Type.

Values within an Enum can be accessed in the same way as properties or can they can be cast from an Int32 value.

In the examples below assume the variable ($)Int has been set to 6.

Expression Result Notes
DayOfWeek.Sunday DayOfWeek.Sunday Where the name is "Sunday" and the value is 0
(DayOfWeek)($)Int DayOfWeek.Saturday Int32 cast to an Enum. Where the name is "Saturday" and the value is 6

For further information, see Enumeration types.

Casting expressions

Casting expressions

Data Types can be cast to other Data Types through the use of explicit casting, this can sometimes result in the loss of information when converting to a type that does not store the same amount of information. Information regarding which types a Data Type can cast to can be found in the “Summary” section under “Can be cast to” in the relevant documentation for that Data Type.

Data Types can be used as other Data Types through the use of implicit casting, this is an automatic process that requires no expression syntax. Information regarding which types a Data Type can be used as can be found in the “Summary” section under “Can be used as” in the relevant documentation for that Data Type.

In the examples below assume the variable ($)Int has been set to 6.

Expression Result Notes
(DayOfWeek)($)Int DayOfWeek.Saturday Int32 cast to an Enum. Where the name is "Saturday" and the value is 6
(Int16)($)Int 6 An Int32 can be cast to an Int16 as long as value is from -32,768 through 32,767
(Int32)1.9 1 Casting a Double to an Int32 will cause any decimal places to be lost
($)Int 6.0 When using a block property of type Double an Int32 is implicitly cast to Double without any expression syntax

For further information, see Explicit Conversions and Implicit Conversions.

Index expressions

Index expressions

Data Types that are Collections or String can have their items accessed using index notation:

  • [0] gets the first item
  • [1] gets the second item
  • ["key"] gets the item with the key "key".

Ranges can also be used within index notation:

  • [0..3] gets three items from the first item (inclusively) (i.e. the first, second, and third item)
  • [^1] gets the last item
  • [^2] gets the second to last item
  • [..] gets all items
  • [..3] gets three items from the first item (inclusively) (i.e. the first, second, and third item)
  • [3..] gets all items from the fourth item (inclusively) (i.e. the fourth to the last item)

For further information on index and range syntax, see Indices and Ranges.

In the examples below assume:

  • ($)List has been set to [1, 2, 3, 4, 5]
  • ($)Dictionary of type Dictionary<string, Int32> has been set to {"FirstKey": 1, "SecondKey": 2}
  • ($)Structure has been set to {"FirstKey": 1, "SecondKey": [1, 2, 3]}
  • ($)String has been set to "Some Text".
Expression Result Notes
($)List[2] 3 The third item in the list is returned
($)List[0..2] [1, 2] The first and second item in the list are returned
($)List[^2] 4 The second to last item in the list is returned
($)List[^2..^0] [4, 5] The second to last and the last item in the list are returned
($)List[1..^1] [2, 3, 4] The second item to the second to last item in the list are returned
($)List[..] [1, 2, 3, 4, 5] All items in the list are returned
($)List[..2] [1, 2] The first item and the second item in the list are returned
($)List[2..] [3, 4, 5] The third item to the last item in the list are returned
($)Dictionary["FirstKey"] 1 The item with the key "FirstKey" is returned
($)Structure["SecondKey"] [1, 2, 3] The item with the key "SecondKey" is returned
($)Structure["SecondKey"][0] 1 The first item within the item with key "SecondKey" is returned
($)String[0] 'S' The first character in the string is returned

Remarks

Known Limitations

Cannot Create Objects using Literal Syntax

Currently, creating an object using literal syntax is not supported.

Objects can be created using expressions, for more information see Constructor expressions.

Cannot Create Dictionaries using Literal Syntax

Currently, creating a dictionary using literal syntax is not supported; any attempt to make a dictionary using literal syntax will create a Structure instead.

Dictionaries can be created using expressions, for more information see Dictionary expressions.

When using variables of the same name the closest scoped is used

It is possible to create multiple variables with the same name in the Variables Grid. When using the same name in different workspaces, the variable with the closest scope will be used.

For example:

  • Top-Level workspace has the variable ($)Variable
  • Child-Level workspace also has the variable ($)Variable

When executing a block in Child-Level that uses ($)Variable, the variable that is used is the variable defined in Child-Level.

This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario.

See Also

External Documentation

6.1.1.3.2.3 - Common Properties

Information regarding properties that are common to all or most blocks.

Common Properties

Summary

There are a number of properties that are common across all or most blocks.

These properties include:

Description Property

The Description property is available on all blocks. It defaults to the name of the block and can be used to describe the action or function the block is performing. Any text entered in the Description property is displayed next to the block’s icon on the workspace.

Description Property

Block Timeout Property

The Block Timeout property is an advanced property available on most blocks. It is used to set a duration of time (using a TimePeriod) that the block must complete its action within, otherwise a BlockTimeoutException is raised.

The default value of null, or a TimePeriod of 0 seconds, indicates that there is no timeout.

Negative TimePeriod values will cause an InvalidBlockTimeoutException to be raised when the block is executed.

Block Timeout Property

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.3.2.4 - Advanced Properties

Information regarding properties that do not normally need to be configured but allow for more advanced scenarios.

Advanced Properties

Summary

Some blocks have advanced properties that do not normally need to be configured but allow for more advanced scenarios (e.g. A block to send emails would have advanced properties for specifying things like cc, bcc, attachments etc.). Advanced properties may have explicit default values or will be initialised with values that allow the block to run without configuration.

All advanced properties are hidden by default and can be shown by Toggling Advanced Properties, their values will be used in the block’s execution regardless of whether they are hidden or shown.

Toggling Advanced Properties

All advanced properties can be shown or hidden using the Show/Hide Advanced Properties button found on the top right of the Property Editor. This button is used to toggle whether properties are shown or hidden.

Toggling Advanced Properties

Finding Advanced Properties

A property is defined as advanced within the documentation of a Block or Data Type.

Information regarding which properties are advanced for a Block can be found in the “Properties” section. The table within each property in the relevant documentation will have an “Is Advanced” row stating whether the property is advanced or not.

Information regarding which properties are advanced for a Data Type can be found in the “Remarks” section under “Advanced Properties” in the relevant documentation for that Data Type.

Remarks

Known Limitations

Toggling advanced properties is not persisted between blocks

Currently, when advanced properties are shown when editing a block the advanced toggle state is not persisted when switching between blocks.

In future this limitation may be removed.

Toggling advanced properties shows or hides all advanced properties

Currently, it is not possible to show or hide individual advanced properties.

In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.3.3 - Handling Exceptions within a Block

Information regarding handling exceptions within a block.

Handling Exceptions within a Block

Summary

Exceptions within a block can be handled at the following levels:

Exceptions thrown within the execution of a block can be handled at the block level by connecting any Handle Block Exception block to the exception output port. Multiple Handle Block Exception blocks can be chained to handle different exceptions.

For more information, see Handling Exceptions.

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.4 - Variables

Information regarding what a variable is, using variables, and variable scopes.

6.1.1.4.1 - What is a Variable?

Information regarding the anatomy of a variable, using variables at design and runtime, and variable typing.

What is a Variable?

Summary

A variable is a named container for storing data that can then be used in Block Properties.

Data in a variable can be read, updated, or removed by different blocks. Examples of these include:

Anatomy of a Variable

Example Variable in Variables Grid

Variables have the following properties that can be configured in the Variables Grid:

Variable Property Notes
Description Description of the variable’s purpose
Name Name of the variable
Type Will default to variable. Read-only, reserved for future use
Set Default Value? Sets the variable to be initialised to the Default Value if set to true, otherwise Default Value is ignored
Default Value The value to initialise the variable to if Set Default Value? is set to true. See Variables with a Default Value
Is Input Variable? Marks the variable as an input if set to true, requiring data to be passed into the variable when the flow is triggered
Is Output Variable? Marks the variable as an output if set to true. All output variables will be returned as items in a Structure. See Output Variables Structure

Variables with a Default Value

Variables can be initialised with a default value. The Default Value can be set to any valid expression or literal, but cannot include any variables.

For example, the following expression is valid as it does not use any variables:

"Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;"

The following expression is invalid as it uses the ($)ServerName variable:

$@"Server={($)ServerName};Database=myDataBase;User Id=myUsername;Password=myPassword;"

Output Variables Structure

When any variables have their Is Output Variable? property set to true, they will be returned to the caller as items in a Structure when the flow ends.

In the following example ($)TotalUnreadEmails and ($)FoldersWithUnreadEmails are both set as outputs and the following Structure is returned:

{
    "TotalUnreadEmails":12,
    "FoldersWithUnreadEmails": {
        "Inbox": 8, 
        "Junk": 4
    }
}

Variables at Design Time

The Variables Grid is used to create, view, modify, and delete variables. It is opened by clicking Variables tab at the bottom of Cortex Studio. For more information see Variables Grid.

Variables can also be created through the use of the Variable Editor. For more information see Creating Variables.

Variables at Runtime

Initialising Variables

Variables must be initialised with data before they can be used in a block.

If an Input or InputOutput property uses a variable that has not been initialised, a Message will be returned stating Variable is not initialised, and the name of the variable will be included within the details of the message. The Message will be:

Variables can be initialised in the following ways:

Flow Input Variable

If a variable has its Is Input Variable? property set to true, and no Default Value has been set, then a value must be provided for the variable when the flow is triggered. When the execution starts, the variable is initialised with the value provided.

Default Value

If a variable has its Set Default Value? property set to true, it will be initialised with the Default Value provided when the flow is executed.

If a variable has its Is Input Variable? and Set Default Value? properties set to true, then it will be initialised with the value provided when the flow is triggered. If no value is provided then it will be initialised with the Default Value.

Block Output Property

Output Properties are used to save values to a variable during the execution of a block, regardless of whether the variable is already initialised or not. The act of saving to an uninitialised variable will initialise it.

Viewing Variables

When debugging a flow in Cortex Studio, selecting an execution will display all initialised variables that are in scope in the Variables Viewer.

Variables Viewer

Viewing Basic Data Types

When a variable contains a basic data type (e.g. String, Integer, etc), the value will be displayed directly in the Variables Viewer. Strings will be surrounded by double quotes (e.g. "MyString").

Viewing Complex Data Types

When a variable contains a complex data type that is not a collection data type (e.g. Command or FlowException), the value will be displayed as Instance of Command or Instance of FlowException respectively in the Variables Viewer.

When a variable contains a collection data type (e.g. Dictionary, List, or Structure), the Variables Viewer will specify the data type and how many items the collection contains (e.g. Dictionary<string, object> with 2 item(s)).

To see the data in the variable, select the variable in the Variables Viewer and the data will be presented in the Variable Details Viewer.

The following examples show the Variable Details Viewer when showing a:

dictionary panel

command panel

exception panel

Updating Variables

InputOutput and Output properties are used to save values and update variables during the execution of a block.

Deleting Variables

When an execution exits a workspace, any variables defined within that workspace’s scope will be deleted from the execution. This means the variables:

  • Are no longer accessible to the execution
  • Are no longer presented in the Variables Viewer when the flow is being debugged

If the execution re-enters the workspace’s scope, any variables will be re-initialised.

Variable Typing

Variables do not have their own data type; they are named containers for storing data of any data type.

When a variable is used in a Block Property it is checked to ensure the data type it contains is supported by the property. For all data types apart from dynamic any variables containing unsupported data types will be displayed in the Messages Grid, preventing the execution from starting; for variables containing dynamic data types checking will be performed during the block execution, throwing an exception if the data type is unsupported.

Sometimes an unsupported data type can automatically be converted to a supported type through the use of implicit casting; if this is possible the block property will handle this without any input required by the developer. However, if this is not possible an unsupported data type must be converted to a supported type by the developer; this can be done by:

  • Explicitly casting the unsupported Data Type
  • Converting the unsupported Data Type through the use of methods and properties (e.g. Convert.ToInt32(($)String) or Int32.Parse(($)String))

For more information on specific data type conversions, see the relevant documentation for that Data Type.

Remarks

Known Limitations

Default Value can not use Variables

Currently, default values cannot use variables. However, this may change in the future.

For examples of valid and invalid default values see Variables with a Default Value.

See Also

External Documentation

None

6.1.1.4.2 - Using Variables

Information regarding using variables in the Variable and Expression editors.

Using Variables

Summary

There are a number of ways to use variables:

Variable Editor

The Variable Editor allows the the developer to create and use variables whilst configuring a block.

Creating a Variable

If a variable does not already exist, the Variable Editor can be used to create a new one at the scope of the selected block.

If the variable name is invalid (does not conform with the C# identifier naming rules) then there will be no option to create a new variable.

Using a Variable

The Variable Editor provides a list of variables that are available at the scope of the selected block.

Typing any text in the Variable Editor will filter the available variables, showing any variable whose name or scope contains the text.

The Variable Editor also allows for:

Using Items in Collections

Variables that contain a Collection or String data type can have their respective items or characters accessed using index notation:

  • [0] gets the first item
  • [1] gets the second item
  • ["key"] gets the item with the key "key".

Ranges can also be used within index notation:

  • [0..3] gets three items from the first item (inclusively) (i.e. the first, second, and third item)
  • [^1] gets the last item
  • [^2] gets the second to last item
  • [..] gets all items
  • [..3] gets three items from the first item (inclusively) (i.e. the first, second, and third item)
  • [3..] gets all items from the fourth item (inclusively) (i.e. the fourth to the last item)

In the examples below assume:

  • ($)List has been set to [1, 2, 3, 4, 5]
  • ($)Dictionary of type Dictionary<string, Int32> has been set to {"FirstKey": 1, "SecondKey": 2}
  • ($)Structure has been set to {"FirstKey": 1, "SecondKey": [1, 2, 3]}
  • ($)String has been set to "Some Text".
Text Result Notes
List[2] 3 The third item in the list is returned
List[0..2] [1, 2] The first and second item in the list are returned
List[^2] 4 The second to last item in the list is returned
List[^2..^0] [4, 5] The second to last and the last item in the list are returned
List[1..^1] [2, 3, 4] The second item to the second to last item in the list are returned
List[..] [1, 2, 3, 4, 5] All items in the list are returned
List[..2] [1, 2] The first item and the second item in the list are returned
List[2..] [3, 4, 5] The third item to the last item in the list are returned
Dictionary["FirstKey"] 1 The item with the key "FirstKey" is returned
Structure["SecondKey"] [1, 2, 3] The item with the key "SecondKey" is returned
Structure["SecondKey"][0] 1 The first item within the item with key "SecondKey" is returned
String[0] 'S' The first character in the string is returned

Using Properties of Data Types

Properties can be used to read data from and/or write data to a variable. The properties accessible are defined by the Data Type, and information regarding properties can be found in the relevant documentation for that Data Type.

Properties can be read-write, read-only, or write-only (extremely rare) depending on the access specified by the Data Type.

Whilst Structures are Collections, they also allow for their keys to be accessed as properties.

In the examples below assume:

  • ($)List has been set to [1, 2, 3]
  • ($)TimePeriod has been set to {"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0}
  • ($)Structure has been set to {"FirstKey": 1, "SecondKey": 2}
Text Result Notes
List.Count 3 Read-only property, this only works in Input Properties
TimePeriod.Years 1 Read-write property, this can be used in Input, Output, and InputOutput Properties. The result column shows reading the property; writing to the property can be achieved by using any Output Property.
Structure.FirstKey 1 Read-write property, this can be used in Input, Output, and InputOutput Properties. The result column shows reading the property; writing to the property can be achieved by using any Output Property.

Using Methods of Data Types

Methods can be used to execute specific functionality. The methods accessible are defined by the Data Type, and information regarding methods can be found in the relevant documentation for that Data Type.

Methods can have parameters passed into them that are then used to execute the functionality, not all methods have parameters. The same method can be defined multiple times, each with different sets of parameters.

In the examples below assume the variable ($)Int has been set to 1.

Text Result Notes
Int.ToString() "1" Method without parameters
Int.ToString("P0") "100%" The ToString() method can take parameters in order to format the result. In this case 1 was converted into a percent with zero decimal places

Expression Editor

Variables are named containers for storing values of any data type; a variable can be included within expressions created using the Expression Editor. A variable is used by prefixing the variable’s name with ($) (e.g. ($)VariableName).

Remarks

Case Sensitivity

When using variables in the Variable or Expression Editor, the names are case insensitive. For example, List is the same as list.

When using properties or methods of any variable, or items in Collections (e.g. Dictionaries, Structures etc.), their names are case sensitive.

For Example:

Text Notes
FlowException.Message Message property cannot be accessed using FlowException.message
Int.ToString() ToString() method cannot be accessed using Int.toString()
Dictionary["Item1"] "Item1" item cannot be accessed using the key Dictionary["item1"]

Known Limitations

When using variables of the same name the closest scoped is used

It is possible to create multiple variables with the same name in the Variables Grid. When using the same name in different workspaces, the variable with the closest scope will be used.

For example:

  • Top-Level workspace has the variable ($)Variable
  • Child-Level workspace also has the variable ($)Variable

When executing a block in Child-Level that uses ($)Variable, the variable that is used is the variable defined in Child-Level.

This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario.

See Also

External Documentation

None

6.1.1.4.3 - Variable Scopes

Information regarding variable scopes, including: what they are, creating variables at a specific scope, and changing a variable’s scope.

Variable Scopes

Summary

Each workspace in a flow has a scope. A scope is where variables are defined and controls where they can be used.

Variables can only be used in the workspace of the scope they are defined in and any descendant workspaces. Only variables in scope will be available in the Variable Editor, or the Expression Editor using snippets. For an example see Accessing Variables from Other Scopes.

When the flow execution exits a workspace, any local-scope variables that have been declared in that workspace are deleted and their values, if any, are lost.

Accessing Variables from Other Scopes

For example, the table below shows a hierarchy of workspaces and which variables are available to each workspace due to their scope:

Workspace Name Parent Workspace Defined Variables Available Variables
Top-Level Workspace N/A
  • GlobalVarA
  • GlobalVarB
  • GlobalVarA
  • GlobalVarB
ChildWorkspace1 Top-Level Workspace
  • ChildVarA
  • ChildVarB
  • GlobalVarA
  • GlobalVarB
  • ChildVarA
  • ChildVarB
ChildWorkspace2 Top-Level Workspace
  • ChildVarC
  • ChildVarD
  • GlobalVarA
  • GlobalVarB
  • ChildVarC
  • ChildVarD
GrandChildWorkspace1 ChildWorkspace1
  • GrandChildVarA
  • GrandChildVarB
  • GlobalVarA
  • GlobalVarB
  • ChildVarA
  • ChildVarB
  • GrandChildVarA
  • GrandChildVarB
GrandChildWorkspace2 ChildWorkspace2
  • GrandChildVarC
  • GrandChildVarD
  • GlobalVarA
  • GlobalVarB
  • ChildVarC
  • ChildVarD
  • GrandChildVarC
  • GrandChildVarD

Creating Variables at a Specific Scope

Variables can be created by using the Variables Grid, or through the use of the Variable Editor. When a new variable is created, it is created in the scope of the currently selected workspace. It is possible to Change a Variable’s Scope

Changing a Variable’s Scope

A variable’s scope can be changed by using the Variables Grid.

Remarks

Known Limitations

When using variables of the same name the closest scoped is used

It is possible to create multiple variables with the same name in the Variables Grid. When using the same name in different workspaces, the variable with the closest scope will be used.

For example:

  • Top-Level workspace has the variable ($)Variable
  • Child-Level workspace also has the variable ($)Variable

When executing a block in Child-Level that uses ($)Variable, the variable that is used is the variable defined in Child-Level.

This may change in future to allow developers to specifically select which of the variables with the same name is used in this scenario.

See Also

External Documentation

None

6.1.1.5 - Data Types

Information regarding what a data type is, and the difference between basic and complex data types.

6.1.1.5.1 - What is a Data Type?

Information regarding what a data type is, basic and complex data types and their differences.

What is a Data Type?

Summary

TODO:

  • Overview of a data type
  • Difference between Value (value types cannot be null, and have a default value that is not null e.g. int is 0) and Reference Data Types (reference types can be null and have a null default value)
  • Difference between Basic and Complex Data Types

Value Types

TODO:

  • Explain what a value type is, and how it can be used
  • Check Set Variable block and how Value Types work within the block
    • Setting a new variable to an already existing value type will cause them to be separate instances of the value
  • The Copy Object block can be used to make a copy of a value type (value types always have a different reference)

Reference Types

TODO:

  • Explain what a reference type is, and how it can be used
  • This is referenced by the Set Variable block
    • Set Variable block is used to set ($)List[0]
    • When adding ($)Reference to ($)List, the actual reference is added (not a copy)
    • Setting value of ($)List1 to ($)List2 will cause them to have the same reference. Changes to ($)List1 are reflected in ($)List2
  • The Copy Object block can be used to make a copy of a type with a different reference

Basic Data Types

TODO:

  • Explain what a basic data type is
  • Table of Basic Data Types
    • Columns - Data Type Name, Value/Reference Type
    • Strings are a basic data type but are also a reference type.

Complex Data Types

TODO:

  • Explain what a complex data type is and what makes a data type complex
  • Includes Complex and Collections (Lists, Dictionaries, structures, etc)
  • Object
  • Dynamic
  • Object vs Dynamic

Remarks

Known Limitations

TODO

See Also

TODO

External Documentation

TODO:

6.1.1.5.2 - Generics

Information regarding generic data types.

Generics

Summary

TODO

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.1.5.3 - Null and Nullable Types

Information regarding null and nullable data types.

Null and Nullable Types

Summary

TODO

Null

TODO

Nullable Types

TODO

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.1.6 - Executions

Information regarding what an execution is, starting executions, execution variables, exceptions thrown during an execution, and execution metadata.

6.1.1.6.1 - What is an Execution?

Information regarding the anatomy of an execution.

What is an Execution?

Summary

An execution represents a running instance of a flow, the execution moves through the flow sequentially executing each block saving any outputs to variables. A flow can have one or more executions running at any time, each with their own variables.

Anatomy of an Execution

Example Execution in Executions Grid

Property Notes Example
Status Icon The Icon representing the current Status of the execution A list of statuses can be found below
Started At The date and time that the execution was started 6 Sep 2022 09:27:45
Updated At The date and time of the last update for the execution 6 Sep 2022 09:27:46
Status The status of the execution A list of statuses can be found below
Block Type The block the execution is currently on Set Variable
Block Description The description of the block the execution is currently on Set Variable
Workspace Name The name of the workspace the execution is currently in Setup and Run Child-Flow
Flow Name The name of the flow the execution is currently running Parent-Flow

When a flow starts the execution of a child flow using the Run Flow block, any child executions will be shown within a tree in the Executions Grid, for example:

Example Child Execution in Executions Grid

Execution Status

Status Description
Running The execution is currently executing
Pausing The execution is in the process of pausing - e.g. a long running block may have to finish before the execution is paused
Paused The execution is paused on top of a block - before the block starts to execute
The execution is paused at a breakpoint on top of a block - before the block starts to execute
The execution is paused on the output port of a block - after the block has executed but before the execution has selected which block is next
Exception The execution is paused on the exception output port - after the block has thrown an exception when break on exception is turned on
Stopping The execution is in the process of stopping - e.g. a long running block may have to finish before the execution is stopped
Stopped The execution has ended after having been manually stopped
Ended The execution has ended normally
Error The execution has ended after having thrown an exception that was not handled

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.6.2 - Executions in Development

Information regarding working with executions in development (i.e. Cortex Studio).

Executions in Development

Summary

Whilst debugging a flow, each execution is represented by a token that moves through the flow, showing which block is currently being executed.

A flow can be debugged in Cortex Studio by clicking the Start an execution button or by making an API call to Cortex Studio, providing input variables to the flow, if required; this will validate the flow a nd then begin an execution.

The following parameters can be specified:

  • Show execution on workspace - when this is true, the token will be shown at every step throughout the flow, otherwise the token will only be shown when the execution pauses, hits a breakpoint, or an exception occurs when Break on exception is true
  • Break on exception - when this is true the execution will pause when an exception occurs

Providing Input Variables

Any flow that has Input Variables defined requires them to be provided when debugging, these may be provided to a flow in the following ways:

Retrieving Output Variables

Any flow that has Output Variables defined can have those variables retrieved after the execution has completed by using the outputVariables in the body of the HTTP response.

Validating a Flow

The flow is validated before it’s debugged, if this is successful an execution will begin.

If there are any issues with the flow then the execution will not start and details of what needs to be resolved will be returned. If the flow was debugged by clicking the Start an execution button, then entries will be displayed in the Messages Grid; if it was debugged by making an HTTP request to Cortex Studio, then a 400 Bad Request is returned.

For a complete list see Validation messages.

Selecting an Execution

One or more executions can be selected within Cortex Studio by clicking on their token, or selecting them using the Executions Grid. This allows:

Interacting with an Execution

Once executions are selected in Cortex Studio they can be interacted with in the following ways:

Set Next Block to Execute

Set Next Block to Execute allows a developer to choose which block will be executed next for the selected execution, even if this block is not connected to the flow.

Examples of what this can be used to do whilst debugging include:

  • Retrying a block due to a transient exception such as network connectivity
  • Retrying a block after using Edit and Continue to fix an incorrectly configured block
  • Skipping over functionality that is not yet working
  • Skipping to specific functionality within the flow in order to test it
  • Running logic that is not part of the flow (e.g. running a clean up script to reset any external data sources for the next execution of the flow)

Currently, Set Next Block to Execute is not available when multiple executions are selected, or the block and execution are on different workspaces.

Edit and Continue an Execution

Edit and Continue allows a developer to pause all executions, and make changes to the flow before continuing debugging.

Examples of what this can be used to do whilst debugging include:

Currently when using Edit and Continue, it is not possible to directly change the value of a variable without using a block.

Viewing an Execution’s Variables

When debugging a flow in Cortex Studio, selecting an execution will display all initialised variables that are in scope in the Variables Viewer.

To see the data in a variable, select the variable in the Variables Viewer and the data will be presented in the Variable Details Viewer. If the data is large enough to negatively affect the performance of Cortex Studio it will not be displayed unless the Load Value Button is clicked.

Viewing an Execution’s Exceptions

When debugging a flow in Cortex Studio, selecting an execution will display all exceptions that have been thrown for that execution in the Exceptions Viewer.

In future, it will be possible to navigate to the block that caused the exception.

Handling an Execution’s Exceptions

Exceptions thrown by an execution can be handled at any level within a flow.

Exceptions can be handled:

If an exception occurs within the workspace of the Handle Flow Exception block and is not handled, the execution will end with a status of Error.

Handling an Execution&rsquo;s Exceptions

Logs Generated

There are two ways that logs are generated while debugging a flow, they are:

Remarks

Known Limitations

Updating a Variable’s value is not possible without using a Block

When using Edit and Continue, it is not possible to directly change the value of a variable without using a block.

In future this limitation may be removed.

Set Next Block to Execute not available when multiple Executions are selected

It is not possible to use Set Next Block to Execute when there are multiple executions selected on the same workspace.

In future this limitation may be removed.

Set Next Block to Execute not available when the Block and Execution are on different Workspaces

It is not possible to use Set Next Block to Execute when the selected execution is not on the same workspace as the block being set next to execute.

In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.6.3 - Executions in Production

Information regarding working with executions in production (i.e. Cortex API Gateway Service).

Executions in Production

Summary

A flow can be started in Production by making an API call to the Cortex API Gateway Service, providing input variables to the flow, if required; this will validate the flow and then begin an execution.

Providing Input Variables

Any flow that has Input Variables defined can have those variables provided by using the inputVariables in the body of the HTTP request.

Retrieving Output Variables

Any flow that has Output Variables defined can have those variables retrieved after the execution has completed by using the outputVariables in the body of the HTTP response

Validating a Flow

The flow is validated before it’s started, if this is successful an execution will begin.

If there are any issues with the flow then the execution will not start and details of what needs to be resolved will be returned. If the flow was started by making an HTTP request to the Cortex API Gateway Service, then a 400 Bad Request is returned.

For a complete list see Validation messages.

Handling an Execution’s Exceptions

Exceptions thrown by an execution can be handled at any level within a flow.

Exceptions can be handled:

If an exception occurs within the workspace of the Handle Flow Exception block and is not handled, the execution will end and then a 500 Internal Server Error is returned.

Logs Generated

There are two ways that logs are generated while executing a flow in Production, they are:

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.7 - Exceptions

Information regarding what an exceptions is, handling exceptions, and throwing exceptions.

6.1.1.7.1 - What is an Exception?

Information regarding the anatomy of an exception, and properties accessible on an exception.

What is an Exception?

Summary

An exception is thrown during an execution when an issue is encountered whilst executing a flow. Exceptions can occur for a number of reasons, such as:

  • Exceptions thrown by a block, these can be found in the relevant documentation for that block (e.g. A duplicate key is added to a Dictionary using the Add Item With Key block)
  • Developer thrown exceptions (e.g. A developer enriches an exception that has already been thrown to provide a more detailed message)
  • Issues with third-party systems (e.g. A third-party system experiences an error)
  • Issues with network connectivity (e.g. A target machine is inaccessible)
  • Issues with permissions (e.g. The execution does not have permission to read a file)
  • Issues with the environment (e.g. The software installed on a target machine is incorrect)

An exception contains details of what caused the issue, for more information see Anatomy of an Exception.

An exception can be handled in different ways depending on where the exception occurred. For more information see Handling Exceptions.

Anatomy of an Exception

Example Exception in Exception Viewer

Data within an exception can be accessed using properties.

The following properties are found on all exceptions:

Property Notes Example
Exception Type The type of the exception PropertyNullException
Message The exception message, providing information about the exception that occurred. This typically includes the cause of the exception, possible resolutions, and any related information. What is included in an exception’s message can be found in the relevant documentation for that exception 'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this.
HelpLink Help link to aid with troubleshooting and resolution for the exception. There are three types of help links:

  • Cortex - Help links direct to material within the Cortex Product Portal. This documentation is written and maintained by Cortex and contains information directly related to the Cortex product.
  • External - Help links direct to externally hosted material about the exception. This documentation is not written or maintained by Cortex.
  • Custom - Help links are generated by flow developers during the design and development of flows. These help links are configured in the Throw New Exception block, and can link to any resource applicable to the exception.
https://v2022.docs.cortex-ia.com/docs/reference/exceptions/common/property/property-null-exception/

The following properties are found on many exceptions:

Property Notes Example
Category The category of the exception, which is used to categorise an exception if there are multiple reasons that the exception can occur. InfiniteLoopException has one category, "Increment"
Error Code The error code for the exception, which is used to indicate the reason that the exception occurred, if there are multiple reasons that the exception can occur. InfiniteLoopException has three error codes, InfiniteLoopErrorCode.IncrementIsZero (100), InfiniteLoopErrorCode.IncrementIsNegative (101), and InfiniteLoopErrorCode.IncrementIsPositive (102)
Inner Exception Contains the exception that caused this exception, if any. This property is always accessible but will only be visible in the Exceptions Viewer when it contains data. {"ExceptionType": "PropertyNullException", "Message": "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this.", "HelpLink": "https://v2022.docs.cortex-ia.com/docs/reference/exceptions/common/property/property-null-exception/"}

For more information regarding what properties are accessible on an exception, see the relevant documentation for that exception.

Remarks

Known Limitations

Carriage Return and Line Feed Characters

Carriage Return and Line Feed characters within an exception are supported but will be displayed or written as \r, \n, or \r\n.

In future this limitation may be removed.

Copying Exception Text

The Exceptions Viewer currently does not support traditional copy functionality. A workaround is to highlight the text, then click and drag into another text editor.

In future this limitation may be removed.

See Also

External Documentation

None

6.1.1.7.2 - Handling Exceptions

Information regarding handling exceptions at the block, workspace and flow level.

Handling Exceptions

Summary

Exceptions within a flow can be handled at the following levels:

Handling Exceptions at the Block level

Example Message in Messages Grid

Exceptions thrown within the execution of a block can be handled by connecting a Handle Block Exception block to the red exception output port. These blocks allow for specific match criteria to be provided; if an exception matches the criteria it will be handled by the block and can be saved to a variable, otherwise, it will be passed to the next chained exception handling block. This process repeats until the exception is either handled or there are no more blocks in the chain; if the exception is not handled at this level it is passed up to the workspace level.

Matching Exceptions

Handle Block Exception blocks can be configured to handle exceptions that match specific criteria (e.g. The Exception Type or Message contains matching text). If an exception matches the criteria, the exception is handled, saved to a variable if provided, and the execution moves to the block connected to the output port; if the exception does not match the criteria the execution moves to the next chained exception handling block.

Chaining Block Exception Handling Blocks

Chaining Block Exception Handling Blocks

Handle Block Exception blocks can be chained together by connecting the red exception output port of one block to the red exception input port of another. When an exception is not handled, it will be passed to the next chained exception handling block. This process repeats until the exception is either handled or there are no more blocks in the chain; if the exception is not handled at this level it is passed up to the workspace level.

The Handle Block Exception block can be used to handle all exceptions. This block does not have an exception output port and therefore ends the chain.

Saving the Block Exception

Handle Block Exception blocks can be used to save the handled exception to a variable. If it is not necessary to save the exception to a variable, it may be discarded by setting the block’s Exception property to use the built-in discard variable ($)_.

Handling Exceptions at the Workspace level

Example Message in Messages Grid

Exceptions not handled at the block level are passed up to the workspace level.

If an unhandled exception occurs in a Nested Workspace where a Handle Workspace Exception block exists:

If an unhandled exception occurs in a Nested Workspace where a Handle Workspace Exception block does not exist:

If an unhandled exception occurs in or reaches the Top-Level Workspace, and is not handled by any Handle Block Exception blocks or the Handle Workspace Exception block, it will be passed up to the flow level.

Please note that there are a number of restrictions when using the Handle Workspace Exception block.

Saving the Workspace Exception

The Handle Workspace Exception block can be used to save the handled exception to a variable. If it is not necessary to save the exception to a variable, it may be discarded by setting the block’s Exception property to use the built-in discard variable ($)_.

Handling Exceptions at the Flow level

Example Message in Messages Grid

If an unhandled exception occurs in or reaches the Top-Level Workspace, and is not handled at the block level or workspace level, it will be passed up to the flow level, where:

The Handle Flow Exception block is automatically added to the Top-Level Workspace when a new flow is created, there are restrictions that apply to this block.

The Handle Flow Exception block it has its own workspace, which can access its own variables and those defined at the scope of the Top-Level Workspace.

The logic contained within the Handle Flow Exception workspace must end the execution using an End Flow block. By default, this workspace contains a Start Workspace block connected to an End Flow block, which will cause the flow to end without error.

Handling Exceptions in the Handle Flow Exception block

Exceptions that occur within the workspace of the Handle Flow Exception block can be handled at the block level and workspace level. If an exception is not handled, the execution will end with a status of Error.

Handling Exceptions in the Handle Flow Exception block

Saving the Flow Exception

The Handle Flow Exception block can be used to save the handled exception to a variable. If it is not necessary to save the exception to a variable, it may be discarded by setting the block’s Exception property to use the built-in discard variable ($)_.

Remarks

Known Limitations

The Top-Level Workspace cannot contain a Handle Workspace Exception block

The Top-Level Workspace cannot contain a Handle Workspace Exception block; if one is added, it will be reported when trying to validate the flow. For more information see Validating a Flow in Development and Validating a Flow in Production.

Any unhandled exceptions thrown on the Top-Level Workspace will be handled by the Handle Flow Exception block.

In the future this may change.

A Nested Workspace cannot contain more than one Handle Workspace Exception block

A Nested Workspace cannot contain more than one Handle Workspace Exception block; if more than one is added, it will be reported when trying to validate the flow. For more information see Validating a Flow in Development and Validating a Flow in Production.

In the future this may change.

Enforced restrictions to prevent infinite recursion

For each execution of a workspace, the Handle Workspace Exception block will only handle the first unhandled exception within its workspace, this is to prevent infinite recursion within the flow.

For more information see Handling Exceptions at the Workspace level.

In the future this may change.

See Also

External Documentation

None

6.1.1.7.3 - Throwing Exceptions

Information regarding throwing an exception within a flow, and scenarios when it is useful to throw an exception.

Throwing Exceptions

Summary

A developer can throw an exception as part of a flow.

Scenarios where throwing exceptions is useful include:

  • A developer throwing a new exception when a flow reaches a state where it cannot complete its defined functionality
  • A developer enriching an exception that has already been thrown to provide more clarity and/or detail
  • A developer rethrowing an exception to propagate the exception to the caller; typically this can be useful when calling another flow

For information about throwing an exception, please see the:

Remarks

Known Limitations

None

See Also

External Documentation

None

6.1.1.8 - Messages

Information regarding what a message is.

6.1.1.8.1 - What is a Message?

Information regarding the anatomy of a message, when a message will occur, and using messages to navigate to issues within a flow.

What is a Message?

Summary

When Starting an Execution in Development using the Start an execution button, the flow will be validated; if there are issues with the flow, messages explaining the issues will be displayed in the Messages Grid.

Some examples of issues that can be raised are:

For a complete list see Validation messages.

Anatomy of a Message

Example Message in Messages Grid

Related messages are grouped by the component affected (e.g. A block, or the Settings Editor)

Each message row contains the following:

Property Notes
Location Path to the specific part of the component that has caused the issue
Summary Short description of the issue
Details Further information about the issue. This may also contain help for resolving the issue

Double clicking on a message within the Messages Grid will navigate the browser to the affected location.

Remarks

Known Limitations

It is not possible to navigate to a nested literal property from a message

It is not possible to navigate to a nested literal property from a message, clicking the message will cause the browser to navigate to the last property of the top-level literal editor that contains the issue.

In future this limitation may be removed.

It is not possible to navigate to the Settings Editor from a message

It is not possible to navigate to the Settings Editor from a message, clicking the message will do nothing.

In future this limitation may be removed.

See Also

External Documentation

None

6.1.2 - Working With...

This section includes all reference documentation for concepts required to use Cortex Innovation.

6.1.2.1 - Collections

Information related to working with collections such as Lists, Dictionaries and Structures.

6.1.2.1.1 - What is a Collection?

Information regarding what a collection is, and the different types of collections.

What is a Collection?

Summary

TODO

Types of Collections

Dictionaries

TODO:

  • Talk about typed dictionaries (TKey, TItem)
  • Talk about heterogenous vs homogenous dictionaries (fix single data type vs multiple data types links in all dictionary blocks)
  • Talk about keys, uniqueness and equality (link to Keys page)
  • Talk about complex keys (link to Keys page)
  • Items can be accessed as indexes
  • Link to Data Type
  • Creating a Dictionary

Accessing Items

Keys

Structures

TODO:

  • Structures are IDictionary<string, object> underlying (how does this interact with blocks?)
    • Talk about {} and dynamic vs object
  • Talk about keys, uniqueness and equality (link to Keys page)
  • Items can be accessed as indexes or properties
  • Link to Data Type
  • Creating a Structure

Accessing Items

Properties
Keys

Lists

TODO:

  • Talk about typed dictionaries (TItem)
  • Talk about [] and dynamic vs object
  • Talk about typed lists
  • Talk about heterogenous vs homogenous lists (fix single data type vs multiple data types links in all list blocks)
  • Items can be accessed as indexes
  • Link to Data Type
  • Creating a List

Accessing Items

Indexes

Arrays vs Lists

Differences

When To Use Arrays

When To Use Lists

Remarks

Known Limitations

Complex Keys do not show sho correctly in the Variable Details Viewer

Currently, if a Dictionary is shown in the Variable Details Viewer and contains Complex Data types as its keys, the data within the variable will not be displayed correctly.

In the future this limitation may be removed.

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.1.2 - Items

Information related to working with Items.

Items

Summary

TODO:

  • Overview/summary
  • What is an Item?
  • How are they accessed?
    • Link to Indexes
    • Link to Keys
  • If you are using C# syntax, then the equality is done using reference equality for reference types, and value equality for value types
  • If you are using List of Dictionary blocks, then the equality is done using reference equality for reference types and falls back to value equality if no reference was found, and value equality for value types

Remarks

Known Limitations

None

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.1.3 - Indexes

Information related to working with Indexes.

Indexes

Summary

TODO:

  • Overview/summary
  • What is an Index?
  • How are they accessed?
  • Indexes are zero based
  • Difference between occurrence and indexes

Accessing an item using Indexes

Indexes can be used in the Expression Editor to access items in a Collection.

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.1.4 - Keys

Information related to working with Keys.

Keys

Summary

TODO:

  • Overview/summary
  • What is a Key?
  • How are they accessed?
  • The type of the Key depends on the data type
  • Keys are unique
  • Keys cannot be null
  • If you are using C# syntax, then the equality is done using reference equality for reference types, and value equality for value types
  • If you are using Dictionary blocks, then the equality is done using reference equality for reference types and falls back to value equality if no reference was found, and value equality for value types

Accessing an item using Keys

Keys can be used in the Expression Editor to access items in a Collection.

Remarks

Known Limitations

Complex Keys do not show sho correctly in the Variable Details Viewer

Currently, if a Dictionary is shown in the Variable Details Viewer and contains Complex Data types as its keys, the data within the variable will not be displayed correctly.

In the future this limitation may be removed.

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.1.5 - Occurrences

Information related to working with Occurrences.

Occurrences

Summary

TODO

  • Summary
  • What is an Occurrence?
  • How are they accessed?
    • Positive or Negative int properties on blocks that operate on single items
  • Difference between occurrence and indexes

Positive Occurrences

TODO:

  • Get First, Second, Third, Nth

Negative Occurrences

TODO:

  • Get Last, Second from Last, Third from Last, Nth from Last

Remarks

Occurrence Not Present

TODO:

Blocks will either throw an exception if the occurrence is not present (e.g. OccurrenceNotPresentException), or they will handle the occurrence not being present either by performing no operation or by returning a predetermined value.

For example:

  • Get Index Of Item With Value (returns predetermined value)
  • Remove Item With Value (no operation performed)
  • Get Item With Key (throws OccurrenceNotPresentException)

Known Limitations

None

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.2 - Culture

Information related to working with Culture.

6.1.2.2.1 - What is a Culture?

Information regarding what a culture is.

What is a Culture?

Summary

TODO

Types of Culture

TODO:

Remarks

Known Limitations

TODO

See Also

TODO: Also need sections in working with text (casing, comparisons/equality, O/S settings), dates and time (formats, O/S settings), numbers (formats, O/S settings) etc specifically for how culture affects things - we can then cross link from here

TODO

TODO

External Documentation

TODO

6.1.2.2.2 - Invariant Culture

Information related to working with Invariant Culture.

Invariant Culture

Summary

TODO: summary

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.2.3 - Current Culture

Information related to working with Current Culture.

Current Culture

Summary

TODO: summary

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.2.4 - Specific Cultures

Information related to working with specific cultures.

Specific Cultures

Summary

TODO: summary

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.2.5 - Custom Cultures

Information related to working with custom cultures.

Custom Cultures

Summary

TODO: summary

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.3 - Data Sources

Information related to working with Data Sources.

6.1.2.3.1 - What is a Data Source?

Information regarding what a data source is.

What is a Data Source?

Summary

TODO

Supported Data Sources

TODO: See Supported Data Sources

Managing Connections to a Data Source

TODO:

  • Connections are managed by the block
  • See Working with Connections (connection life cycle, using a variable for connections over literal/expression)

Remarks

Known Limitations

Limited Set of Supported Data Sources

Currently, there are a limited set of Supported Data Sources.

In the future this limitation may be removed.

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.3.2 - Supported Data Sources

Information regarding supported data sources.

6.1.2.3.2.1 - ODBC

Information regarding ODBC as a data source.

ODBC

Summary

TODO:

  • Summary
  • Table or other format to display verified data sources (e.g. postgres, mysql, access, excel, oracle) and examples (link to connection strings)

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.3.2.2 - SQL Server

Information regarding SQL Server as a data source.

SQL Server

Summary

TODO:

  • Summary
  • Table or other format to display verified data sources (SQL Server versions) and examples (link to connection strings)

Remarks

TODO:

  • Connected as the user running the service or as a custom user (e.g. trusted user vs username and password)
    • can have issues when there is a difference in permissions between the flow debugger service user vs flow execution service user
    • check that impersonation works with trusted when implemented

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.4 - Date and Time

Information related to working with Date and Time.

6.1.2.4.1 - What is Date and Time?

Information regarding what Date and Time is.

What is Date and Time?

Summary

TODO:

  • Date and Time are represented by different data types
    • DateTime
    • DateTimeOffset
    • TimeSpan
    • TimePeriod
  • What is the difference between DateTime and DateTimeOffset?
    • When should they be used
  • What is the difference between TimeSpan and TimePeriod?
    • When should they be used
  • We don’t deal with timezone issues within the blocks
  • Offsets are handled within DateTimeOffset and can be dealt with using our blocks
  • Useful link - https://learn.microsoft.com/en-us/dotnet/api/system.datetime?view=net-6.0

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.4.2 - Date and Time Formatting

This page describes the concept of Date and Time Formatting, including Format Providers, Format Templates and Format Specifiers.

Date and Time Formatting

Overview

TODO:

  • Overview/summary
  • Common formats ISO8601, Invariant Culture

Format providers

TODO:

  • what are they
  • ways of creating
    • CultureInfo.InvariantCulture
    • CultureInfo.CurrentCulture
    • new CultureInfo("")
    • new CultureInfo(“en-GB”)

or

https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#datetimeformatinfo-properties

https://learn.microsoft.com/en-us/dotnet/api/system.globalization.datetimeformatinfo?view=net-5.0

Invariant Culture

TODO:

Current Culture

TODO

Format Templates

Format templates use characters called format specifiers to define the text representation of DateTimeOffset and DateTime values.

There are two types of format template:

Both can be used to define how DateTimeOffset and DateTime values are converted to and from their text representation.

TODO:

  • *How do they relate to format providers

Standard Format Templates

A standard format template uses a single character format specifier to define the text representation of DateTimeOffset and DateTime values and can be used to define how DateTimeOffset and DateTime values are converted to and from their text representation.

The following table shows all of the standard format templates.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Pattern Format Specifier DateTimeOffset Example DateTime Example Notes
Short Date Pattern d 2022-07-01T14:00:00.0000000+01:00 -> 1/7/2022 TODO See short date (“d”) format specifier for further information
Short Time Pattern t 2022-07-01T14:00:00.0000000+01:00 -> 2:00 PM TODO See short time (“t”) format specifier for further information
Long Date Pattern D 2022-07-01T14:00:00.0000000+01:00 -> 5 April 2022 TODO See long date (“D”) format specifier for further information
Long Time Pattern T 2022-07-01T14:00:00.0000000+01:00 -> 2:00:00 PM TODO See long time (“T”) format specifier for further information
Full Date/Time Pattern (Short Time) f 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See full date short time (“f”) format specifier for further information
Full Date/Time Pattern (Long Time) F 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See full date long time (“F”) format specifier for further information
General Date/Time Pattern (Short Time) g 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See general date short time (“g”) format specifier for further information
General Date/Time Pattern (Long Time) G 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See general date long time (“G”) format specifier for further information
Round-Trip Date/Time Pattern O, o 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See round-trip (“O”, “o”) format specifier for further information
RFC1123 Pattern R, r 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See RFC1123 (“R”, “r”) format specifier for further information
Sortable Date/Time Pattern s 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See sortable (“s”) format specifier for further information
Universal Sortable Date/Time Pattern u 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See universal sortable (“u”) format specifier for further information
Universal Full Date/Time Pattern U 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See universal full (“U”) format specifier for further information
Month Day Pattern M, m 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See month (“M”, “m”) format specifier for further information
Year Month Pattern Y, y 2022-07-01T14:00:00.0000000+01:00 -> TODO TODO See year month (“Y”) format specifier for further information
Unknown Pattern Any other single character N/A N/A Throws a FormatException

Invariant Format Templates

TODO:

  • Invariant format templates -
    • In some cases, the standard format string serves as a convenient abbreviation for a longer custom format string that is invariant. Four standard format strings fall into this category: “O” (or “o”), “R” (or “r”), “s”, and “u”. These strings correspond to custom format strings defined by the invariant culture. They produce string representations of date and time values that are intended to be identical across cultures. The following table provides information on these four standard date and time format strings.
    • TABLE 2
      • Standard format string Defined by DateTimeFormatInfo.InvariantInfo property Custom format string
      • “O” or “o” None yyyy’-‘MM’-‘dd’T’HH’:‘mm’:‘ss’.‘fffffffK
      • “R” or “r” RFC1123Pattern ddd, dd MMM yyyy HH’:‘mm’:‘ss ‘GMT’
      • “s” SortableDateTimePattern yyyy’-‘MM’-‘dd’T’HH’:‘mm’:‘ss
      • “u” UniversalSortableDateTimePattern yyyy’-‘MM’-‘dd HH’:‘mm’:‘ss’Z’
      • https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings

ISO 8601 Standard

TODO:

  • round-trip “O”, “o” and sortable “s” complies with ISO
  • yyyy-MM-ddTHH:mm:ss.fffffffK for DateTime
  • yyyy-MM-ddTHH:mm:ss.fffffffzzz for DateTimeOffset

Custom Format Templates

TODO:

Format specifiers

TODO:

  • what are they
  • Table of them
  • Some of the commonly used format specifiers are:
    • dd: The day of the month, from 01 through 31
    • MM: The month, from 01 through 12
    • yyyy: The year as a four-digit number
    • HH: The hour, using a 24-hour clock from 00 to 23
    • hh: The hour, using a 12-hour clock from 01 to 12
    • mm: The minute, from 00 through 59
    • ss: The second, from 00 through 59
    • fff: The number of milliseconds
    • tttt: The AM/PM designator
    • The full set of allowed format specifiers are as per standard Microsoft .NET Custom Date and Time Format Strings.

Operating System Settings

TODO:

TODO Add concepts page for string/object formatting that links to:

TODO Add concepts page for formatting numbers that links to:

TODO: https://learn.microsoft.com/en-us/dotnet/standard/base-types/parsing-datetime

TODO: Update examples for most common en-gb os formats

6.1.2.5 - Email

Information related to working with email.

6.1.2.5.1 - Authentication

Information regarding authentication when working with email

Authentication

Overview

Setting up an app password for a Gmail account

Setting up a Gmail account for OAuth authentication

Setting up an Outlook account for OAuth authentication using client credentials

Setting up an Outlook account for OAuth authentication using certificate credentials

6.1.2.5.2 - What is Email?

Information regarding what email is.

What is Email?

Summary

TODO:

  • SMTP (Sending)
    • Attachments (best practices):
      • where should attachments be in relation to the server the flow is executing on
      • should we link to the file path stuff (working with files and folders)?
  • IMAP (Retreiving)
    • Mailboxes
    • Folders:
      • Deleted?
    • Emails:
      • Attachments
      • Status:
        • Read
        • Unread
      • Priority
      • Body Format
      • Flagged
  • SSL/TLS
  • Authentication:
    • Unauthenticated Servers
    • SASL
      • SMTP Server
      • Gmail?
    • OAuth:
      • Gmail OAuth
      • Microsoft365 OAuth

Managing Connections to a Mail Server

TODO:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.6 - Enums

Information related to working with enum data types such as DayOfWeek, DateTimeComponentType and SearchOptions.

6.1.2.6.1 - What is an Enum?

Information regarding what an Enum is.

What is an Enum?

Summary

TODO:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.7 - Files and Folders

Information related to working with Files and Folders.

6.1.2.7.1 - What are Files and Folders?

Information regarding what files and folders are.

What are Files and Folders?

Summary

TODO:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.7.2 - Attributes

Information regarding file and folder attributes.

Attributes

Summary

TODO:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.7.3 - Paths

Information regarding file and folder paths.

Paths

Summary

TODO:

  • Supported file and folder path formats and examples of using them
  • How we determine is a path is a folder or a file
    • path\ = folder (path with terminating \ or /)
    • path = folder (path not ending in extension)
    • path.extension = file (path ending in extension)
    • path.anotherpartofpath\ = folder (as it ends in a \ or /)
  • Valid file and folder names

Links:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.8 - Loops

Information related to working with loops, such as for and for each.

6.1.2.8.1 - What is a Loop?

Information regarding what a loop is.

What is a Loop?

Summary

TODO:

  • Introduce concept of loop
    • Why are they used
  • Types of Loops (pros and cons)
    • For loop
      • Can move forwards or backwards
      • Can move by single or multiple increments
      • Can modify a collection while iterating over it
      • Have to manually manage the bounds of the loop
      • Index can be adjusted to break a loop
      • Decision blocks can be used to break a loop
    • For each
      • Cannot modify the collection during a for each loop (use a for loop if the collection needs to be modified during the loop)
      • Decision blocks can be used to break a loop
    • While
      • No blocks, can be done using decision blocks looping back into the flow (order of decision block determines while or do while loop)
      • Condition can be adjusted to break a loop early
      • Decision blocks can be used to break a loop early
    • Do while
      • No blocks, can be done using decision blocks looping back into the flow (order of decision block determines while or do while loop)
      • Condition can be adjusted to break a loop early
      • Decision blocks can be used to break a loop early
  • Nested loops
    • Why they are used
    • How nested loops affect performance
  • Infinite loops
    • Why they are bad, how to avoid
    • for loop block protects against infinite loops
    • for each loop block cannot have infinite loops as the collection cannot be modified
    • while/ do while does not have any protection against infinite loops (must be managed within the flow)

Links:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.9 - Numbers

Information related to working with Numbers.

6.1.2.9.1 - What is a Number?

Information regarding what a number is.

What is a Number?

Summary

TODO:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.10 - Objects

Information related to working with Objects.

6.1.2.10.1 - What is an Object?

Information regarding what an object is.

What is an Object?

Summary

TODO:

  • What is the difference between an object and a data type?
    • Data Type is the definition, Object is an instance of that definition
  • Explain Object Data Type, base foundation of classes

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.10.2 - Object Casting

Information regarding casting an object to different data types.

Object Casting

Summary

TODO

Implicit Cast

TODO

Explicit Cast

TODO

Object vs dynamic

TODO

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.10.3 - Object Equality

Information regarding object equality, and what defines two objects as equal.

Object Equality

Summary

TODO

https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/statements-expressions-operators/equality-comparisons

Value Type vs Reference Type Equality

TODO:

Value Type Equality

TODO: notes about value equality and a worked through example

Reference Type Equality

TODO: notes about reference equality and a worked through example

How Cortex compares objects for equality

TODO: notes about how cortex compares and a worked through example

Notes:List and Dictionary equality is slightly different to normal equality as it will compare first based on reference and then fall back to value - compared to == .Equals .ReferenceEquals - blocks affected

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11 - Text

Information related to working with Text.

6.1.2.11.1 - What is Text?

Information regarding what text is.

What is Text?

Summary

TODO:

Links:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.2 - Casing

Information regarding text casing.

Casing

Summary

TODO:

  • Best Practices
    • Comparing strings - do not lower or upper pick a relevant culture or ignore case

Links:

Common types of text casing

There are many different types of text casing.

The table below lists some of the most common types of text casing:

Name Example Notes
lowercase "this is lowercase" All letters in all words are lower cased.
UPPERCASE "THIS IS UPPERCASE" All letters in all words are capitalized.
Title Case "This Is Title Case" First letter in all words is capitalized, all other letters are lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased; spaces and punctuation are preserved.
camelCase "thisIsCamelCase" First letter in all words (except the first) is capitalized, all other letters are lower cased, and all spaces and punctuation are removed.
PascalCase "ThisIsCamelCase" First letter in all words is capitalized, all other letters are lower cased, and all spaces and punctuation are removed.

Culture Info

Culture Info specifies the culture-specific casing rules used to determine how the case of text is changed.

The table below lists the most common supported culture info:

Name Text Value Description
Invariant Culture CultureInfo.InvariantCulture Used to compare text using culture-sensitive sort rules and the Invariant Culture. Case of the texts is considered when comparing.
Current Culture CultureInfo.CurrentCulture Used to compare text using culture-sensitive sort rules and the Current Culture. Case of the texts is considered when comparing.

In addition to Invariant and Current Culture, there are two other types of culture that can be used:

For more information about culture info, please see CultureInfo.

Invariant Culture

For Invariant Culture, the casing rules used to determine how the case of text is changed are not culture-sensitive.

TODO:

If a security decision depends on a string comparison or a case-change operation, the application should use the InvariantCulture to ensure that the behavior is consistent regardless of the culture settings of the system. However, the invariant culture must be used only by processes that require culture-independent results, such as system services. Otherwise, it produces results that might be linguistically incorrect or culturally inappropriate.

Current Culture

For Current Culture, the casing rules used to determine how the case of text is changed are culture-sensitive and based on the culture of the operating system the flow execution is running on.

TODO:

  • Link to Working with Culture -> Current Culture
  • When to use? If not sure what to choose?
  • Best practices - all OSes in cluster should be installed with same OS culture and settings etc. - should also be time sync’d
  • Notes about current culture and a worked through example

Specific Cultures

TODO:

Custom Cultures

TODO:

  • Talk about how there can be custom cultures installed, each with their own casing rules
  • When to use? If not sure what to choose?
  • Link to Working with Culture -> Custom Cultures

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO:

  • Convert to Uppercase
  • etc

External Documentation

TODO

6.1.2.11.3 - Converting Objects To Text

Information regarding converting objects to their text representation.

Converting Objects To Text

Summary

TODO

Using Blocks

TODO:

  • Explain that blocks can be used - maybe with examples or link to examples within the block documentation
    • Format Text With Value
    • Format Text With Values
    • Join Text
    • Convert Date Time To Text
    • Convert Object To Text - need to make it clear how this works - does tostring and if tostring returns class name does json serialisation
    • Convert Object To Json - need to make it clear how this works - does json serialisation

Using Expressions

ToString()

TODO:

  • .ToString() - talk about that some objects will just return their name, text formatting format providers etc.
  • Convert.ToString()
  • Examples and where to find in Data Types documentation

String interpolation

See Interpolated Strings.

String.Format()

TODO: String.Format

Remarks

Known Limitations

Support for {{}} is Missing

Using {{VariableName}} expression syntax to convert a variable to its String representation is currently not supported.

It is possible to convert a variable to its string representation within an expression by using the ToString() method (e.g. ($)VariableName.ToString())

In future this limitation may be removed.

See Also

TODO

TODO

TODO:

  • Format Text With Value
  • Format Text With Values
  • Join Text
  • Convert Date Time To Text
  • Convert Object To Text - need to make it clear how this works - does tostring and if tostring returns class name does json serialisation
  • Convert Object To Json - need to make it clear how this works - does json serialisation

External Documentation

TODO

6.1.2.11.4 - Empty Text and Whitespace

Information regarding empty text and whitespace.

Empty Text and Whitespace

Summary

TODO:

  • What is an Empty Text?
  • What is Whitespace?
  • Difference between empty text and whitespace

Empty Text

TODO:

  • How to create an empty text - "" or String.Empty

Whitespace

https://learn.microsoft.com/en-us/dotnet/api/system.char.iswhitespace?view=net-5.0#System_Char_IsWhiteSpace_System_Char_ and textual representation \t \r \n etc.

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.5 - Encoding

Information regarding text encoding.

Encoding

Summary

TODO:

  • Available encodings
  • How to define them/use them
    • Different ways to specify encoding:
      • Encoding encoding = Encoding.GetEncoding(20127);
      • Encoding encoding = new ASCIIEncoding();
      • Encoding encoding = Encoding.ASCII;

Links:

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.6 - Equality

Information regarding text equality.

Equality

Summary

TODO:

  • Best Practices
    • Use Ordinal to remove ambiguity and increase performance
    • Comparing strings - do not lower or upper pick a relevant culture or ignore case

Links:

Comparison Types

Comparison Types specify the rules used to determine whether two pieces of text match.

The table below lists the supported comparison types:

Name Text Value Numeric Value Description
Ordinal StringComparison.Ordinal 4 Used to compare text using ordinal sort rules. Case of the texts is considered when comparing.
Ordinal Ignore Case StringComparison.OrdinalIgnoreCase 5 Used to compare text using ordinal sort rules. Case of the texts is ignored when comparing.
Invariant Culture StringComparison.InvariantCulture 2 Used to compare text using culture-sensitive sort rules and the invariant culture. Case of the texts is considered when comparing.
Invariant Culture Ignore Case StringComparison.InvariantCultureIgnoreCase 3 Used to compare text using culture-sensitive sort rules and the invariant culture. Case of the texts is ignored when comparing.
Current Culture StringComparison.CurrentCulture 0 Used to compare text using culture-sensitive sort rules and the current culture. Case of the texts is considered when comparing.
Current Culture Ignore Case StringComparison.CurrentCultureIgnoreCase 1 Used to compare text using culture-sensitive sort rules and the current culture. Case of the texts is ignored when comparing.

For more information about comparison types, please see StringComparison.

TODO: Consider moving sections below into the StringComparison Data Type documentation and removed from this page

Ordinal

TODO:

  • When to use? If not sure what to choose?
  • Ordinal sort rules
  • notes about ordinal and a worked through example

Ordinal Ignore Case

TODO:

  • When to use? If not sure what to choose?
  • Link to Ordinal sort rules, only difference is that it doesn’t consider casing when comparing characters
  • notes about ordinal ignore case and a worked through example

Invariant Culture

TODO:

  • When to use? If not sure what to choose?
  • Link to Culture -> Invariant Culture
  • Invariant Culture rules
  • notes about invariant culture and a worked through example

Invariant Culture Ignore Case

TODO:

  • When to use? If not sure what to choose?
  • Link to Culture -> Invariant Culture
  • Link to Invariant Culture sort rules, only difference is that it doesn’t consider casing when comparing characters
  • notes about invariant culture ignore case and a worked through example

Current Culture

TODO:

  • When to use? If not sure what to choose?
  • Link to Culture -> Current Culture
  • Current Culture rules
  • notes about current culture and a worked through example

Current Culture Ignore Case

TODO:

  • When to use? If not sure what to choose?
  • Link to Culture -> Current Culture
  • Link to Current Culture sort rules, only difference is that it doesn’t consider casing when comparing characters
  • notes about current culture ignore case and a worked through example

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.7 - Formatting

Information regarding text formatting.

Formatting

Summary

TODO:

  • What formatting is
  • How to format text
    • Blocks
    • Expression
  • How does text formatting use DateTime Formatting and Number Formatting?
    • Link to Working With -> Date and Time -> Date and Time Formatting
    • Link to Working With -> Number -> Number Formatting

Using Blocks

TODO:

  • Explain that blocks can be used - maybe with examples or link to examples within the block documentation
    • Convert Object to Text
    • Format Text with Value
    • Format Text with Values

Using Expressions

TODO: How to format using an expression

String Interpolation

TODO:

  • mention that convert object to text is close to behaviour of string interpolation, but not everything is covered - e.g. no expression support or indexing - recommendation is to use string.interpolation inline as more powerful and saves block licensing

Format Providers

TODO:

  • what are they
  • ways of creating
    • CultureInfo.InvariantCulture
    • CultureInfo.CurrentCulture
    • new CultureInfo("")
    • new CultureInfo(“en-GB”)

Format Templates

TODO:

  • Find C# link
  • Talk about what a template is and how format parameters are used (e.g. "{0}")
  • curly brackets need to be escaped when using the $ and $@ prefixes

Format Specifiers

TODO:

TODO: Control formatting

TODO: Control spacing

TODO: Control alignment

TODO: Composite formatting

TODO: Format Item

TODO: Anything else relevant on formatting links above

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.8 - Pattern Matching Syntax

Information regarding pattern matching syntax.

Pattern Matching Syntax

Summary

TODO

  • What is pattern matching?
    • how is it different to contains or regex
  • Pattern matching can only be used in blocks
  • * is 0 or more
  • ? is 0 or 1
  • to use these as literals use \\* \\?
  • Common pattern matching
    • **/*.ext (Check that this works)
    • Common file extensions to search for, how to search for them *.txt, *.pdf
      • Link to Files and Folders for list of common extensions

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO

External Documentation

TODO

6.1.2.11.9 - Regex Syntax

Information regarding .Net regex syntax.

Regex Syntax

Summary

TODO:

TODO: Options

Links:

Character Classes

TODO:

  • Include information about any builtin snippets for each regex

A character class matches any of a set of characters. Character classes include the language elements listed in the following table.

Syntax Description Pattern Matches
[characters] Matches any character found in characters. [oz] o in Cortex
[^characters] Matches any character not found in characters. [^oz] C, r, t, e, x in Cortex
[first-last] Matches any character in the range of characters from first to last. [A-C] C in Cortex
. Wildcard. Matches any character except \n. C.r Cor in Cortex
\p{category} Matches any character in a category of Unicode characters, specified by category. To see what you can use for category, please check the supported Unicode general categories and the supported named blocks. \p{Lu} C in Cortex
\P{category} Matches any character not in a category of Unicode characters, specified by category. To see what you can use for category, please check the supported Unicode general categories, and the supported named blocks. \P{Lu} o, r, t, e, x in Cortex
\w Matches any letter, decimal digit, or an underscore. \w C, o, r, t, e, x in Cortex !
\W Matches any character except a letter, decimal digit, or an underscore. \W ! in Cortex !
\s Matches any white-space character. \w\s x  in Cortex !
\S Matches any character except a white-space character. \s\S  ! in Cortex !
\d Matches any decimal digit. \d 7 in Cortex 7!
\D Matches any character except a decimal digit. \D C, o, r, t, e, x,  , ! in Cortex 7!

https://learn.microsoft.com/en-us/dotnet/standard/base-types/character-classes-in-regular-expressions#SupportedUnicodeGeneralCategories https://learn.microsoft.com/en-us/dotnet/standard/base-types/character-classes-in-regular-expressions#supported-named-blocks

Character Escapes

TODO:

  • Include information about any builtin snippets for each regex

The following table lists the character escapes supported by regular expressions in .NET.

Syntax Description Pattern Matches
\r Matches a carriage return. \r\n(\w+) \r\nCortex in \r\nCortex with\na new line
\n Matches a newline. \r\n(\w+) \r\nCortex in \r\nCortex with\na new line
\t Matches a tab. (\w+)\t Cortex1\t, Cortex2\t in Cortex1\tCortex2\t
[\b] Matches a backspace. Note that it must be enclosed in brackets to have this meaning. [\b]{3,} \b\b\b\b in \b\b\b\b
\f Matches a form feed. [\f]{2,} \f\f\f in \f\f\f
\e Matches an escape. \e \x001B in \x001B
\v Matches a vertical tab. [\v]{2,} \v\v\v in \v\v\v
\a Matches the bell character. \a \u0007 in Cortex ‘\u0007’
\octal Matches a character, where octal is the octal representation of that character. \w\040\w x C in Cortex Cortex
\xhex Matches a character, where hex is the two-digit hexadecimal representation of that character. \w\x20\w x C in Cortex Cortex
\uunicode Matches a Unicode character, where unicode is the four digit hexadecimal representation of that Unicode character. \w\u0020\w x C in Cortex Cortex
\ccharacter Matches an ASCII control character specified by character. \cC \x0003 in \x0003

Quantifiers

TODO:

  • Include information about any builtin snippets for each regex

A quantifier specifies how many instances of the previous element (which can be a character, a group, or a character class) must be present in the input string for a match to occur. Quantifiers include the language elements listed in the following table.

Syntax Description Pattern Matches
* Matches previous element zero or more times. co*rtex crtex, cortex, coortex, coooortex in crtex cortex coortex coooortex
+ Matches previous element one or more times. co+rtex cortex, coortex, coooortex in crtex cortex coortex coooortex
? Matches previous element zero or one times. co?rtex crtex, cortex in crtex cortex coortex coooortex
{n} Matches previous element exactly n times. co{2}rtex coortex in crtex cortex coortex coooortex
{n,} Matches previous element at least n times. co{2,}rtex coortex, coooortex in crtex cortex coortex coooortex
{n,m} Matches previous element at least n times and at most m times. co{1,2}rtex cortex, coortex in crtex cortex coortex coooortex
*? Matches previous element zero or more times, but as few times as possible. cort(ex)*? cort in cortexexex
+? Matches previous element one or more times, but as few times as possible. cort(ex)+? cortex in cortexexex
?? Matches previous element zero or one time, but as few times as possible. cort(ex)?? cort in cortexexex
{n,}? Matches previous element at least n times, but as few times as possible. cort(ex){2,}? cortexex in cortexexex
{n,m}? Matches previous element at least n times and at most m times, but as few times as possible. cort(ex){1,3}? cortex in cortexexex

Anchors

TODO:

  • Include information about any builtin snippets for each regex

Anchors cause a match to succeed or fail depending on the current position in the string.

Syntax Description Pattern Matches
^ Matches the beginning of the input. ^\w{3} Cor in Cortex
$ Matches the end of the input, or the point before a final \n at the end of the input. \w{3}$ tex in Cortex
\A Matches the beginning of the input. Identical to ^, except it is unaffected by the multi-line option. \A\w{3} Cor in Cortex
\z Matches the end of the input, without exception. \w{3}\z tex in Cortex
\Z Matches the end of the input, or the point before a final \n at the end of the input. Identical to $, except it is unaffected by the multi-line option. \w{3}\Z tex in Cortex
\G Matches the point that the previous match ended. Used to find contiguous matches. \G\D*\s Cortex , reads  in Cortex reads 7 files
\b Matches any word boundary. Specifically, any point between a \w and a \W. \b\w+\s\w+\b Cortex reads, Cortex writes in Cortex reads Cortex writes
\B Matches any point that is not a word boundary. Specifically, any point not between a \w and a \W. \Brt\w*\b rtex, rtex in Cortex reads Cortex writes

Grouping Constructs

TODO:

  • Include information about any builtin snippets for each regex

Grouping constructs delineate sub-expressions of a regular expression and typically capture sub-strings of an input string. Grouping constructs include the language elements listed in the following table.

Syntax Description Pattern Matches
(subpattern) Captures subpattern as an unnamed group. (\w)\1 oo in Coortex
(?<name>subpattern) Captures subpattern as a named group specified by name. (?<double>\w)\k<double> oo in Coortex
(?<name-previous>subpattern) Balancing group definition. This allows nested constructs to be matched, such as parentheses or HTML tags. The previously defined group to balance against is specified by previous. Captures subpattern as a named group specified by name, or name can be omitted to capture as an unnamed group. (((?<open><span>)[^<]*)+([^<]*(?<close-open></span>))+)+(?(open)(?!)) <span>Cortex this is included</span>, <span>Cortex this is included too</span> in not included <span>Cortex this is included</span> not included either <span>Cortex this is included too</span>
(?:subpattern) Non-capturing group. Allows the use of parentheses without subpattern being captured into a group. Cortex\s(?:include)? Cortex include, Cortex  in Cortex include Cortex not include
(?enabled-disabled:subpattern) Allows subpattern to be matched with different options than the rest of the pattern. Any inline option characters in enabled or disabled will enable or disable specific options, respectively. To see what inline option characters are available, please check the regular expressions options. (?i:c|v)(ortex) cortex, Cortex, Vortex in cortex Cortex Vortex CORTEX
(?=subpattern) Zero-width positive look-ahead assertion. Continues matching only if subpattern matches on the right. \w+(?=ex\b) Cort, Vort in Cortex Vortex Balloon
(?!subpattern) Zero-width negative look-ahead assertion. Continues matching only if subpattern does not match on the right. \b\w+\.(?!exe)\w+\b cortex.jpg, cortex.html in cortex.jpg cortex.html .*.html cortex.exe
(?<=subpattern) Zero-width positive look-behind assertion. Continues matching only if subpattern matches on the left. (?<=\(\$\))\w+ variable, 22 in ($)variable ($)22 ($)–
(?<!subpattern) Zero-width negative look-behind assertion. Continues matching only if subpattern does not match on the left. \b\w(?<![aeiou])\w* Cortex, words, which, does, not, start, with, vowel, like in Cortex words which does not start with a vowel like all
(?>subpattern) Prevents backtracking over subpattern, which can improve performance. [cv](?>o+r+) cor, coor, vor in cortex coortex vortex gortex

Back-reference Constructs

TODO:

  • Include information about any builtin snippets for each regex

A back-reference allows a previously matched sub-expression to be identified subsequently in the same regular expression. The following table lists the back-reference constructs supported by regular expressions in .NET.

Syntax Description Pattern Matches
\number Matches the value of a previously captured group, specified by number. \b(\w)\w*\1\b xcortex, that in Finds all words like xcortex that start and end with the same letter
\k<name> Matches the value of a previously captured named group, specified by name. (?<punctuation>\p{P})\w+\k<punctuation> !cortex!, ?cortex? in !cortex! ?cortex? XcortexX

Alternation Constructs

TODO:

  • Include information about any builtin snippets for each regex

Alternation constructs changes a regular expression to enable either/or matching. These constructs include the language elements listed in the following table.

Syntax Description Pattern Matches
| Functions as a logical or. Matches any elements it separates. (c|v)ortex cortex, vortex in cortex vortex xortex
(?(subpattern)yes|no) Treats subpattern as a zero-width assertion to check if it matches. If so, attempts to match with the yes subpattern. Otherwise, tries the no subpattern. The |no part is optional. \b(?(\w+tez\b)\w{3}|cortex) cortex, cor in cortex cortez vortex
(?(group)yes|no) Checks if a previously defined group was successfully captured, specified by group, which can be a number or a name for a named group. If so, attempts to match with the yes subpattern. Otherwise, tries the no subpattern. The |no part is optional. (?(<quoted>\(\$\)))\w+|'\w+' cortex, ‘cortex’ in ($)cortex ‘cortex’

Substitutions

TODO:

  • Include information about any builtin snippets for each regex

Substitutions are regular expression language elements supported in replacement patterns.

Syntax Description Pattern Replacement Result
$number Substitutes the value of a group, specified by number. \b(\w+)(\s)(\w+)\b $3$2$1 Cortex Great becomes Great Cortex
${name} Substitutes the value of a named group, specified by name. \b(?<word1>\w+)(\s)(?<word2>\w+)\b ${word2} ${word1} Cortex Great becomes Great Cortex
$$ Substitutes the $ character. \b(dollar) $$ (dollar)name becomes ($)name
$& Substitutes the entire match. \w+ \*\*$&\*\* Cortex becomes **Cortex**
$` Substitutes all input text found before the match. #+ $` Co##rtex becomes CoCortex
$' Substitutes all input text found after the match. #+ $' Cort##ex becomes Cortexex
$+ Substitutes the last group captured. Co(r) $+ CoCortex becomes Cortex
$_ Substitutes the entire input. \w+? $_  Cortex becomes Cortex Cortex Cortex Cortex Cortex Cortex 

Remarks

Known Limitations

TODO

See Also

TODO

TODO

TODO: List blocks which support using regex

TODO: All blocks which support regex should link back here from the properties that support it

External Documentation

TODO

6.2 - APIs

This section includes all reference documentation for APIs.

6.2.1 - Cortex API Gateway Service

This section includes all reference documentation for the APIs exposed by the Cortex API Gateway Service.

6.2.2 - Cortex Flow Debugger Service

This section includes all reference documentation for the APIs exposed by the Cortex Flow Debugger Service.

6.2.3 - Cortex Flow Execution Service

This section includes all reference documentation for the APIs exposed by the Cortex Flow Execution Service.

6.2.4 - Cortex Gateway

This section includes all reference documentation for the APIs exposed by Cortex Gateway.

6.2.5 - Cortex Studio

This section includes all reference documentation for the APIs exposed by Cortex Studio.

6.3 - Blocks

This section includes all reference documentation for functional blocks.

6.3.1 - Data

Blocks related to working with data sources.

6.3.1.1 - Execute Data Command

Blocks related to executing commands against data sources.

6.3.1.1.1 - Execute Data Command

Connects to a specific data source and executes a Command, returning any object from the Command’s result.

Icon

Execute Data Command

(Cortex.Blocks.Data.ExecuteDataCommand.ExecuteDataCommandBlock`1)

Description

Connects to a data source (e.g. SQL Server) using the specified Connection Details, and executes a Command (e.g. SELECT * FROM Table), returning the Result.

Close Connection can be specified to choose whether the connection to the data source is closed or is kept open for use on subsequent Execute Command blocks.

Examples

Selecting Rows

This example will select all rows and columns from a connected SQL Server data source which have an Id less than 3, saving the rows to the Result.

A QueryCommand is used throughout this example to select data from the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}}

In this example ($)Command has been set using the following Expression:

new QueryCommand("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3})
($)Command is a variable of type QueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Selecting all rows and columns that have an Id less than 3 from Table using a QueryCommand results in the variable ($)Result being updated to the following:

[
    { 
        "Id": 1, 
        "FirstColumn": "FirstColumn1", 
        "SecondColumn": "SecondColumn1"
    },
    { 
        "Id": 2, 
        "FirstColumn": "FirstColumn2", 
        "SecondColumn": "SecondColumn2"
    }
]

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands. For an example of a non parameterised command please see Executing Multiple Commands (Unsafe)


Inserting Rows

This example will insert a new row into a connected SQL Server data source, saving the number of rows inserted to the Result.

A NonQueryCommand is used throughout this example to insert data into the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", "Parameters": { "InsertParameter1": \"FirstColumn4\", "InsertParameter2": \"SecondColumn4\" } }

In this example ($)Command has been set using the following Expression:

new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", new { InsertParameter1 = "FirstColumn4", InsertParameter2 = "SecondColumn4" })
($)Command is a variable of type NonQueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Inserting a new row into Table using a parameterised NonQueryCommand results in the variable ($)Result being updated to the following:

1

This indicates that 1 row has been inserted into Table, with Table being updated to:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"
4 "FirstColumn4" "SecondColumn4"

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands. For an example of a non parameterised command please see Executing Multiple Commands (Unsafe)


Updating Rows

This example will update all rows on a connected SQL Server data source which have an Id less than 3, saving the number of rows updated to the Result.

A NonQueryCommand is used throughout this example to update data in the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter", "Parameters": { "UpdateParameter": 3 } }

In this example ($)Command has been set using the following Expression:

new NonQueryCommand("UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter", new {UpdateParameter = 3})
($)Command is a variable of type NonQueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Updating all rows that have an Id less than 3 in Table using a NonQueryCommand results in the variable ($)Result being updated to the following:

2

This indicates that 2 rows have been updated in Table, with Table being updated to:

Id FirstColumn SecondColumn
1 "Updated" "SecondColumn1"
2 "Updated" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands. For an example of a non parameterised command please see Executing Multiple Commands (Unsafe)


Deleting Rows

This example will delete all rows on a connected SQL Server data source which have an Id less than 3, saving the number of rows deleted to the Result.

A NonQueryCommand is used throughout this example to delete data in the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "DELETE FROM Table WHERE Id < @DeleteParameter", "Parameters": { "DeleteParameter": 3 } }

In this example ($)Command has been set using the following Expression:

new NonQueryCommand("DELETE FROM Table WHERE Id < @DeleteParameter", new {DeleteParameter = 3})
($)Command is a variable of type NonQueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Deleting all rows that have an Id less than 3 in Table using a NonQueryCommand results in the variable ($)Result being updated to the following:

2

This indicates that 2 rows have been deleted in Table, with Table being updated to:

Id FirstColumn SecondColumn
3 "FirstColumn3" "SecondColumn3"

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands. For an example of a non parameterised command please see Executing Multiple Commands (Unsafe)


Using Functions

This example will select the maximum Id value from a connected SQL Server data source, saving the value of the function to the Result.

A QueryCommand is used throughout this example to select the maximum Id value from the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "SELECT Max(Id) FROM Table", "Parameters": null}

In this example ($)Command has been set using the following Expression:

new QueryCommand("SELECT Max(Id) FROM Table", null)
($)Command is a variable of type QueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Selecting the maximum Id value from Table using a QueryCommand results in the variable ($)Result being updated to the following:

[
    { 
        "": 3
    }
]

Note that the AS keyword can be used to give aliases to results, for example the CommandText "SELECT Max(Id) AS MaxId FROM Table;" would have resulted in the variable ($)Result being updated to [ { "MaxId": 3 } ]; the AS keyword also allows for Using Multiple Functions.


Using Multiple Functions

This example will select the maximum Id value as MaxId and the minimum Id value as MinId from a connected SQL Server data source, saving the values of the functions to the Result.

A QueryCommand is used throughout this example to select the maximum Id value as MaxId and the minimum Id value as MinId from the data source, however, both an Command or Commands could also be used to the same effect.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "SELECT Max(Id) AS MaxId, Min(Id) AS MinId FROM Table", "Parameters": null}

In this example ($)Command has been set using the following Expression:

new QueryCommand("SELECT Max(Id) AS MaxId, Min(Id) AS MinId FROM Table", null)
($)Command is a variable of type QueryCommand
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Selecting the maximum Id value as MaxId and the minimum Id value as MinId from Table using a QueryCommand results in the variable ($)Result being updated to the following:

[
    { 
        "MaxId": 3,
        "MinId": 1 
    }
]

Executing Multiple Commands (Safe)

This example will select, insert, update and delete from a connected SQL Server data source, using a parameterised command. The result of each command will be saved to the result.

An Commands is used throughout this example, as it is the only type of Command that allows you to execute and return the results of multiple commands.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter; DELETE FROM Table WHERE Id < @DeleteParameter; SELECT * FROM Table", "Parameters": { "SelectParameter": 3, InsertParameter1 = \"FirstColumn4\", InsertParameter2 = \"SecondColumn4\", "UpdateParameter": 3, "DeleteParameter": 3 }}

In this example ($)Command has been set using the following Expression:

new Commands("SELECT * FROM Table WHERE Id < @SelectParameter; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter; DELETE FROM Table WHERE Id < @DeleteParameter; SELECT * FROM Table", new {SelectParameter = 3, InsertParameter1 = "FirstColumn4", InsertParameter2 = "SecondColumn4", UpdateParameter = 3, DeleteParameter = 3})
($)Command is a variable of type Commands
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Running the Commands results in the variable ($)Result being updated to the following:

[
    [
        { 
            "Id": 1, 
            "FirstColumn": "FirstColumn1", 
            "SecondColumn": "SecondColumn1"
        },
        { 
            "Id": 2, 
            "FirstColumn": "FirstColumn2", 
            "SecondColumn": "SecondColumn2"
        }
    ],
    1,
    2,
    2,
    [
        { 
            "Id": 3, 
            "FirstColumn": "FirstColumn3", 
            "SecondColumn": "SecondColumn3"
        },
        { 
            "Id": 4, 
            "FirstColumn": "FirstColumn4", 
            "SecondColumn": "SecondColumn4"
        }
    ]
]
  • The first item of ($)Result represents the rows selected by the first select statement (SELECT * FROM Table WHERE Id < @SelectParameter).
  • The second item of ($)Result indicates that 1 row has been inserted into Table (INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)).
  • The third item of ($)Result indicates that 2 rows have been updated in Table (UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter).
  • The fourth item of ($)Result indicates that 2 rows have been deleted in Table (DELETE FROM Table WHERE Id < @DeleteParameter).
  • The fifth item of ($)Result represents the rows selected by the second select statement (SELECT * FROM Table).

Table has been updated to:

Id FirstColumn SecondColumn
3 "FirstColumn3" "SecondColumn3"
4 "FirstColumn4" "SecondColumn4"

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands. For an example of a non parameterised command please see Executing Multiple Commands (Unsafe)


Executing Multiple Commands (Unsafe)

This example will select, insert, update and delete from a connected SQL Server data source, using String Interpolation instead of parameters. The result of each command will be saved to the result.

An Commands is used throughout this example, as it is the only type of Command that allows you to execute and return the results of multiple commands.

The data source contains a Table with the following rows and columns before the command is executed:

Id FirstColumn SecondColumn
1 "FirstColumn1" "SecondColumn1"
2 "FirstColumn2" "SecondColumn2"
3 "FirstColumn3" "SecondColumn3"

In this example assume the following variables have been set before the command has been executed:

  • ($)SelectParameter with the value 3
  • ($)InsertParameter1 with the value "FirstColumn4"
  • ($)InsertParameter2 with the value "SecondColumn4"
  • ($)UpdateParameter with the value 3
  • ($)DeleteParameter with the value 3

Properties

Property Value Notes
Command ($)Command, with value {"CommandText": "SELECT * FROM Table WHERE Id < 3; INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"FirstColumn1\", \"SecondColumn2\"); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < 3; DELETE FROM Table WHERE Id < 3; SELECT * FROM Table", "Parameters": null}

In this example ($)Command has been set using the following Expression:

new Commands($"SELECT * FROM Table WHERE Id < {($)SelectParameter}; INSERT INTO Table (FirstColumn, SecondColumn) VALUES ({($)InsertParameter1}, {($)InsertParameter2}); UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < {($)UpdateParameter}; DELETE FROM Table WHERE Id < {($)DeleteParameter}; SELECT * FROM Table", null)
($)Command is a variable of type Commands
Connection Details ($)ConnectionDetails, with value {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} ($)ConnectionDetails is a variable of type SqlServerConnectionDetails
Close Connection ($)CloseConnection, with value true ($)CloseConnection is a variable of type Boolean
Result ($)Result, with no value ($)Result will be set to the type dynamic

Result

Running the Commands results in the variable ($)Result being updated to the following:

[
    [
        { 
            "Id": 1, 
            "FirstColumn": "FirstColumn1", 
            "SecondColumn": "SecondColumn1"
        },
        { 
            "Id": 2, 
            "FirstColumn": "FirstColumn2", 
            "SecondColumn": "SecondColumn2"
        }
    ],
    1,
    2,
    2,
    [
        { 
            "Id": 3, 
            "FirstColumn": "FirstColumn3", 
            "SecondColumn": "SecondColumn3"
        },
        { 
            "Id": 4, 
            "FirstColumn": "FirstColumn4", 
            "SecondColumn": "SecondColumn4"
        }
    ]
]
  • The first item of ($)Result represents the rows selected by the first select statement (SELECT * FROM Table WHERE Id < @SelectParameter).
  • The second item of ($)Result indicates that 1 row has been inserted into Table (INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)).
  • The third item of ($)Result indicates that 2 rows have been updated in Table (UPDATE Table SET FirstColumn = \"Updated\" WHERE Id < @UpdateParameter).
  • The fourth item of ($)Result indicates that 2 rows have been deleted in Table (DELETE FROM Table WHERE Id < @DeleteParameter).
  • The fifth item of ($)Result represents the rows selected by the second select statement (SELECT * FROM Table).

Table has been updated to:

Id FirstColumn SecondColumn
3 "FirstColumn3" "SecondColumn3"
4 "FirstColumn4" "SecondColumn4"

Note that using a Parameterised Command helps prevent against SQL Injection, for more information please see Parameterised Commands.


Properties

Command

The Command executed on the connected data source. There are multiple Command Types that can be used, each with a different purpose:

  • Command: Parses a single statement provided in the commandText, determining how the statement should be executed against the data source. If the commandText is a Query Statement the rows retrieved from the data source will be returned, otherwise if the commandText is a Non Query Statement the number of rows affected will be returned.
  • Commands: Parses single or multiple statements provided in the commandText, determining how each statement should be executed against the data source. If a Query Statement is executed rows retrieved from the data source are added as an entry of the result, If a Non Query Statement is executed the number of rows affected is added as an entry of the result.
  • QueryCommand: Executes the given commandText as a Query Statement, returning the rows retrieved from the data source.
  • NonQueryCommand: Executes the given commandText as a Non Query Statement, returning the number of rows affected from the data source.
Data Type DataCommand
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Command with value {"CommandText": "", "Parameters": null}

Connection Details

The Connection Details object that includes all of the information required to connect to a data source, including:

For a list of currently supported connection details, please see ConnectionDetails

Note it is recommended to use a Variable for Connection Details when it will be used across multiple Execute Command blocks, as using a variable will allow for reuse of the same connection. Using a Literal to set the Connection Details will cause the connection to only be used once.

Data Type ConnectionDetails
Property Type Input
Is Advanced false
Default Editor Literal
Default Value SqlServerConnectionDetails with value {"ConnectionString": "Server=localhost;Database=YourDatabase;Trusted_Connection=true;"}

Close Connection

Close Connection can be specified to choose whether the connection to the data source is closed or is kept open for use on subsequent Execute Command blocks, this defaults to false if left blank, please see Closing Connections for more information.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Result

The object returned from the data source.

Depending on the type of Command, the data returned within the Result will vary. Please see Command Types for more information on what data will be returned by each type.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Result with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when the Command is null.
Thrown when the commandText within the Command is null.
Thrown when the Connection Details is null.
Thrown when the connectionString within the Connection Details is null.
PropertyEmptyException Thrown when the commandText within the Command is empty.
Thrown when the connectionString within the Connection Details is empty.
InvalidConnectionStringException Thrown when an invalid connection string has been supplied (e.g. The connection string contains an invalid argument "NotAnArgument = False").
Thrown when a required connection string argument has not been supplied (e.g. The server requires encryption and the connection string contains "Encrypt=False").
CommandException Thrown when the data source was not found or was not accessible.
Thrown when an error occurs whilst trying to open a new connection.
Thrown when a connection is successfully established but an error occurred during the login process.
Thrown when the Command contains syntax errors. The error will contain a nested SqlException with a corresponding SqlException Error Code.
Thrown when the Command is invalid for the table specified.
Thrown when the Command references a non-existent stored procedure.
Thrown when parameters derives from Array or IEnumerable when a Query Statement is executed.
Thrown when an Command contains multiple statements.

Remarks

Command Types

There are multiple types of Command that can be used, each with a different purpose:

Command

A Command parses a single statement provided in the commandText, determining how the statement should be executed against the data source. If the commandText is a Query Statement the rows retrieved from the data source will be returned, otherwise if the commandText is a Non Query Statement the number of rows affected will be returned.

For a Query Statement (e.g. select and execute):

Result will be set to when
List<Structure> with a single item Single item is returned
List<Structure> with many items Many items are returned
List<Structure> with no items No items are returned

For a Non Query Statement (e.g. insert, update, delete, etc)

Result will be set to when                                                        
Int32 with a value of 1 Single row is affected
Int32 with a value greater than 1 Many rows are affected
Int32 with a value of 0 No rows are affected

If multiple statements are provided in CommandText, the block will throw a CommandException as this type can only run single statements.

If performance is a key consideration it is recommended to use a QueryCommand or NonQueryCommand instead of Command as they do not parse the commandText.

Commands

A Commands parses single or multiple statements provided in the commandText, determining how each statement should be executed against the data source. If a Query Statement is executed rows retrieved from the data source are added as an entry of the result, If a Non Query Statement is executed the number of rows affected is added as an entry of the result.

For each Query Statement (e.g. select and execute):

Result will have the following entry added when
List<Structure> with a single item Single item is returned
List<Structure> with many items Many items are returned
List<Structure> with no items No items are returned

For each Non Query Statement (e.g. insert, update, delete, etc)

Result will have the following entry added when                                  
Int32 with a value of 1 Single row is affected
Int32 with a value greater than 1 Many rows are affected
Int32 with a value of 0 No rows are affected

If performance is a key consideration it is recommended to use a QueryCommand or NonQueryCommand instead of Commands as they do not parse the commandText.

Note that the Commands should not be used for commands that have dependency between their statements (e.g. Cursors and Variables). Please see Complex Commands for more information on how to deal with these.

QueryCommand

A QueryCommand executes the given commandText as a Query Statement, returning the rows retrieved from the data source. If the commandText contains multiple select statements, only the results of the first Query Statement will be returned.

For a Query Statement (e.g. select):

Result will be set to when
List<Structure> with a single item Single item is returned
List<Structure> with many items Many items are returned
List<Structure> with no items No items are returned

For a Non Query Statement (e.g. insert, update, delete, etc)

Result will be set to                                                                                         when
null always, as Non Query Statements do not return data

Note use a QueryCommand for commands that have dependency between their statements (e.g. Cursors and Variables) and return data from the data source. Please see Complex Commands for more information.

NonQueryCommand

A NonQueryCommand executes the given commandText as a Non Query Statement, returning the number of rows affected from the data source. If the command contains multiple statements, the sum of all the results will be returned.

For a Query Statement (e.g. select):

Result will be set to                                                                                 when
Int32 with a value of -1 always, as Query Statements do not return data

For a Non Query Statement (e.g. insert, update, delete, etc)

Result will be set to when
Int32 with a value of 1 Single row is affected
Int32 with a value greater than 1 Many rows are affected
Int32 with a value of 0 No rows are affected

Note use a NonQueryCommand for commands that have dependency between their statements (e.g. Cursors and Variables) and return the number of rows affected. Please see Complex Commands for more information.

Statement Types

There are two categories of statements Query and Non Query.

Query Statements

Query Statements are used to retrieve data from a data source, for example selecting all rows from a table in a database, Query Statements return the data selected by the Statement as a List<Structure> when used in an Command, an Commands, or a QueryCommand. If a Query Statement is used in a NonQueryCommand -1 will be returned as Query Statements do not affect rows.

Examples of Query Statements can be found here:

A Query Statement can use any object as a parameter. Objects that derive from Array or IEnumerable can only be used for clauses that accept list values (e.g. IN, ANY, ALL), if they are used in other clauses the block will throw a CommandException.

Non Query Statements

Non Query Statements are used to manipulate the data within a data source, for example deleting all rows from a table in a database, Non Query Statements return the number of rows affected by the Statement as an Int32 value when used in an Command, an Commands, or a NonQueryCommand. If a Non Query Statement is used in a QueryCommand null will be returned as Non Query Statements do not return data.

Examples of Non Query Statements can be found here:

A Non Query Statement can use any object as a parameter. If an object that derives from Array or IEnumerable is used, the Non Query Statement will be executed for each item in the Array or IEnumerable and the sum of all the results will be returned.

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the Command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "SELECT * FROM Table WHERE Name = @Parameter"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

Query Statements can use any object as a parameter. Objects that derive from Array or IEnumerable can only be used for clauses that accept list values (e.g. IN, ANY, ALL), if they are used in other clauses the block will throw a CommandException.

Non Query Statements can use any object as a parameter. If an object that derives from Array or IEnumerable is used, the Non Query Statement will be executed for each item in the Array or IEnumerable and the sum of all the results will be returned.

For both Query Statements and Non Query Statements, an SqlException is thrown if a parameter is missing from the Command and the CommandText contains a parameter (e.g. {"CommandText": "SELECT * FROM Table WHERE Name = @Parameter", "Parameters": {"IncorrectParameter": 0}}).

Complex Commands

Complex commands (e.g. Cursors and Variables) that contain dependency between their statements cannot be used with Commands, as the parsing performed by the block will cause each statement of CommandText to be run individually instead of running the CommandText as a whole.

For statements with this type of dependency use either QueryCommand or NonQueryCommand, depending on whether data from the data source or the number of rows affected is returned.

Connection Strings

A connection string must be provided within the Connection Details in order to connect to a data source. The connection string is formatted differently depending on the type of data source, please see Working with Data Sources for more information.

Please see Working with Data Sources for a list of supported data sources and how to construct valid connection strings for them.

Opening Connections

The Execute Command block automatically handles creating and opening connections for the specified Connection Details using the following rules:

  • If a connection does not exist, a new connection will be created, opened and used when the block runs.
  • If a connection already exists but is closed, the connection will be opened and used when the block runs.
  • If a connection already exists and is open, the connection will used the block runs.

If a Variable is used to pass in the Connection Details it can be used to keep the connection alive across multiple Execute Command blocks as long as Close Connection is set to false. Keeping the connection open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening connections for each execution.

If a Literal or an Expression is used to create the Connection Details a new connection will always be made when the Execute Command block runs and if Close Connection is set to false the connection will be closed automatically at some point after the block finishes and before the flow ends.

For information on how to explicitly close a connection, please see Closing Connections.

Closing Connections

Connections can be explicitly closed by setting Close Connection to true. This causes the connection to be closed after the Command has been executed.

If a Variable is used to pass in the Connection Details and Close Connection is set to false the connection will be closed when the Variable goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see Variables.

If a Literal or an Expression is used to create the Connection Details and Close Connection is set to false the connection will be closed automatically at some point after the Execute Command block finishes and before the flow ends.

For information on how to open a connection, please see Opening Connections.

Why does the Result property return a dynamic data type?

The decision for the Result to return a dynamic data type rather than a specific type, was to avoid users having to cast the Result to its correct type to be able to use all of its properties.

As a result, any issues with using the Result (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the Result to its correct type.

Known Limitations

When using a Parameterised Command to execute a stored procedure, it is not possible to write back to output parameters.

6.3.2 - Date & Time

Blocks related to working with Date and Time.

6.3.2.1 - Add Time Period

Add a time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) to a date time.

6.3.2.1.1 - Add Time Period

Adds a Time Period to a specified Date Time.
Icon

Add Time Period

(Cortex.Blocks.DateAndTime.AddTimePeriod.AddTimePeriodBlock)

Description

Adds a Time Period to the specified Date Time.

This block can add both positive and negative TimePeriod values.

Examples

Add a positive Time Period

This example will add 1 year, 1 month, 1 day, 1 hour and 30 minutes to 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Time Period ($)TimePeriod, with value of {"Years": 1, "Months": 1, "Days": 1, "Hours": 1, "Minutes": 30, "Seconds": 0, "Milliseconds": 0} ($)TimePeriod is a variable of type TimePeriod

Result

Adding 1 year, 1 month, 1 day, 1 hour and 30 minutes to 2021-01-01T00:00:00+00:00 will result in the variable ($)DateTime being updated. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2022-02-02T01:30:00+00:00"

Add a negative Time Period

This example will add -1 year to 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Time Period ($)TimePeriod, with value of {"Years": -1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0} ($)TimePeriod is a variable of type TimePeriod

Result

Adding -1 year from 2021-01-01T00:00:00+00:00 will result in 1 year being subtracted and the variable ($)DateTime being updated. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2020-01-01T00:00:00+00:00"

Properties

Date Time

The Date Time to add the Time Period to.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Time Period

The Time Period to add to the Date Time to.

Time Period can have positive and negative components where components are:

  • Years
  • Months
  • Days
  • Hours
  • Minutes
  • Seconds
  • Milliseconds

When adding a Time Period, the block will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds.

When adding months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. adding one month onto 2021-01-31T23:59:59+00:00 will equate to 2021-02-28T23:59:59+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type TimePeriod
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Years: 0
Months: 0
Days: 0
Hours: 0
Minutes: 0
Seconds: 0
Milliseconds: 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when adding Time Period to Date Time will result in the Date Time being less than 0001-01-01T00:00:00+00:00. See Property Less Than Minimum Value.
Thrown when adding Time Period to Date Time will result in the Date Time being greater than 9999-12-31T23:59:59+00:00. See Property Greater Than Maximum Value.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Order of calculations

When adding a Time Period, the block will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds.

Addition of Months

When adding months to the Date Time, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. adding one month onto 2021-01-31T23:59:59+00:00 will equate to 2021-02-28T23:59:59+00:00).

Daylight Savings

This block copes with UTC time offsets but does not know anything about which time zone the Date Time represents; as a result it cannot take daylight savings into account as these are related to time zones rather than UTC time offsets.

6.3.2.2 - Convert Date Time

Convert a date time to and from text.

6.3.2.2.1 - Convert Date Time To Text

Converts a Date Time to Text.
Icon

Convert Date Time To Text

(Cortex.Blocks.DateAndTime.ConvertDateTime.ConvertDateTimeToTextBlock)

Description

Converts a Date Time to Text.

Additional options can be specified:

  • Format Template can be specified to define the format the Date Time should be converted to (e.g. "dd/MM/yyyy").
  • Format Provider can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting).

Examples

ISO 8601 Standard Format

This example will convert a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset) to the ISO 8601 Standard format (i.e. "yyyy-MM-ddTHH:mm:ss.fffffffzzz").

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value null ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting a Date Time representing midnight on 31st December 2021 (with a 0 UTC time offset and without specifying any format template or provider) will result in the variable ($)Text being updated to the following ISO 8601 Standard text representation:

"2021-12-31T00:00:00.0000000+00:00"

Default format for Invariant Culture

This example will convert a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset) to the default format for Invariant Culture (i.e. "MM/dd/yyyy HH:mm:ss zzz").

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value CultureInfo.InvariantCulture ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting a Date Time representing midnight on 31st December 2021 (with a 0 UTC time offset and without a format template), but specifying Invariant Culture text representation, will result in the variable ($)Text being updated to the following:

"12/31/2021 00:00:00 +00:00"

Full Date Long Time format for Invariant Culture

This example will convert a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset) to the Full Date Long Time format for Invariant Culture (i.e. "dddd, dd MMMM yyyy HH:mm:ss").

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Format Template ($)FormatTemplate, with value "F" ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value CultureInfo.InvariantCulture ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting a Date Time representing midnight on 31st December 2021 (with a 0 UTC time offset), and specifying the Full Date Long Time format for Invariant Culture, will result in the variable ($)Text being updated to the following:

"Friday, 31 December 2021 00:00:00"

Default format for American English (“en-US”)

This example will convert a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset) to the default format for American English "en-US" (i.e. "MM/d/yyyy h:m:s tt zzz").

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting a Date Time representing midnight on 31st December 2021 (with a 0 UTC time offset and without a format template), but specifying an American English "en-US" text representation, will result in the variable ($)Text being updated to the following:

"12/31/2021 12:00:00 AM +00:00"

Full Date Long Time format for American English (“en-US”)

This example will convert a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset) to the Full Date Long Time format for American English "en-US" (i.e. "dddd, MMMM d, yyyy h:m:s tt").

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Format Template ($)FormatTemplate, with value "F" ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting a Date Time representing midnight on 31st December 2021 (with a 0 UTC time offset), and specifying the Full Date Long Time format for American English "en-US", will result in the variable ($)Text being updated to the following:

"Friday, December 31, 2021 12:00:00 AM"

Properties

Date Time

The Date Time to convert to Text.

By default, if no Format Template or Format Provider are specified, the resultant Text will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Format Template

Format Template can be specified to define the format the Date Time should be converted to (e.g. "dd/MM/yyyy" -> "31/12/2021").

If Format Template contains valid format specifiers (e.g. "dd" for 2 digit day representation), they will be subsitituted based on the Date Time; characters that are not format specifiers will be passed through as literal text.

If Format Template is not specified, null or empty (i.e. ""), the default format template of the specified Format Provider is used. If Format Provider is also not specified or null the ISO 8601 Standard format will be used (i.e. "yyyy-MM-ddTHH:mm:ss.fffffffzzz").

For information about format templates and specifiers, please see Date and Time Formatting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value yyyy-MM-ddTHH:mm:ss.fffffffzzz

Format Provider

Format Provider can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting.).

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Data Type IFormatProvider
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Text

The Text representation of the Date Time.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
FormatException Thrown when Format Template is a single invalid format specifier (i.e. "a").

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Format Template and Specifiers

Please note that changes to operating system date and time formats, could result in some of the examples above displaying different results.

For information about format templates and specifiers, please see Date and Time Formatting.

Null or Empty Format Template

If Format Template is not specified, null or empty (i.e. ""), the default format template of the specified Format Provider is used. If Format Provider is also not specified or null the ISO 8601 Standard format will be used (i.e. "yyyy-MM-ddTHH:mm:ss.fffffffzzz").

Null Format Provider

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

6.3.2.2.2 - Convert Text To Date Time

Converts Text to a Date Time.
Icon

Convert Text To Date Time

(Cortex.Blocks.DateAndTime.ConvertDateTime.ConvertTextToDateTimeBlock)

Description

Converts Text to a Date Time.

Additional options can be specified:

  • Format Template can be specified to explicity define the format of the Text (e.g. "dd/MM/yyyy").
  • Format Provider can be specified to define the cultural rules used to control the conversion (e.g. new CultureInfo("en-US") will apply American English rules to the conversion).

Examples

ISO 8601 Standard Format

ISO 8601 Standard format is "yyyy-MM-ddTHH:mm:ss.fffffffzzz".

This example will convert "2021-12-31T00:00:00.0000000+00:00" to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset).

Properties

Property Value Notes
Text ($)Text, with value "2021-12-31T00:00:00+00:00" ($)Text is a variable of type String
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value null ($)FormatProvider is a variable of type IFormatProvider
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Converting "2021-12-31T00:00:00.0000000+00:00" to a Date Time (without specifying any format template or provider) will result in the variable ($)DateTime being updated to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00.0000000+00:00"

Default format for Invariant Culture

Default format for Invariant Culture is "MM/dd/yyyy HH:mm:ss zzz".

This example will convert "12/31/2021 00:00:00 +00:00" to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset).

Properties

Property Value Notes
Text ($)Text, with value "12/31/2021 00:00:00 +00:00" ($)Text is a variable of type String
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value CultureInfo.InvariantCulture ($)FormatProvider is a variable of type IFormatProvider
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Converting "12/31/2021 00:00:00 +00:00" to a Date Time without specifying a format template but specifying Invariant Culture, will result in the variable ($)DateTime being updated to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00.0000000+00:00"

Full Date Long Time format for Invariant Culture

Full Date Long Time format for Invariant Culture is "dddd, dd MMMM yyyy HH:mm:ss".

This example will convert "Friday, 31 December 2021 00:00:00" to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset).

Property Value Notes
Text ($)Text, with value "Friday, 31 December 2021 00:00:00" ($)Text is a variable of type String
Format Template ($)FormatTemplate, with value "F" ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value CultureInfo.InvariantCulture ($)FormatProvider is a variable of type IFormatProvider
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Converting "Friday, 31 December 2021 00:00:00" to a Date Time specifying the Full Date Long Time format for Invariant Culture, will result in the variable ($)DateTime being updated to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00.0000000+00:00"

Default format for American English (“en-US”)

Default format for American English (“en-US”) is "MM/d/yyyy h:m:s tt zzz".

This example will convert "12/31/2021 12:00:00 AM +00:00" to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset).

Property Value Notes
Text ($)Text, with value "12/31/2021 12:00:00 AM +00:00" ($)Text is a variable of type String
Format Template ($)FormatTemplate, with value null ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Converting "12/31/2021 12:00:00 AM +00:00" to a Date Time without specifying a format template but specifying American English "en-US", will result in the variable ($)DateTime being updated to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00.0000000+00:00"

Full Date Long Time format for American English (“en-US”)

Full Date Long Time format for American English (“en-US”) is "dddd, MMMM d, yyyy h:m:s tt".

This example will convert "Friday, December 31, 2021 12:00:00 AM" to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset).

Properties

Property Value Notes
Text ($)Text, with value "Friday, December 31, 2021 12:00:00 AM" ($)Text is a variable of type String
Format Template ($)FormatTemplate, with value "F" ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Converting "Friday, December 31, 2021 12:00:00 AM" to a Date Time specifying the Full Date Long Time format for American English "en-US", will result in the variable ($)DateTime being updated to a Date Time representing midnight on 31st December 2021 (with 0 UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00.0000000+00:00"

Properties

Text

The Text to convert to a Date Time.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Format Template

Format Template can be specified to define the format the Text is in (e.g. "dd/MM/yyyy").

If Format Template does not contain any valid format specifiers (e.g. "ww/ww/wwww") and the text exactly matches the Format Template (e.g. "ww/ww/wwww"), then Date Time is set to a DateTimeOffset value that represents the current Date and Time.

If Format Template is not specified, null or empty (i.e. ""), the ISO 8601 Standard format will be used for the conversion (i.e. "yyyy-MM-ddTHH:mm:ss.fffffffzzz").

If the ISO 8601 Standard format fails, then the default template of the specified Format Provider will be used; if there is no specified Format Provider, then Invariant Culture rules will be used instead.

For information about format templates and specifiers, please see Date and Time Formatting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value yyyy-MM-ddTHH:mm:ss.fffffffzzz

Format Provider

Format Provider can be specified to define the cultural rules used to control the conversion (e.g. new CultureInfo("en-US") will apply American English rules to the conversion).

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Data Type IFormatProvider
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Date Time

The Date Time that has been converted from Text.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
FormatException Thrown when Format Template does not contain any valid specifiers (e.g. "ww/ww/wwww").
Thrown when Format Template contains non-specifier characters, and Text does not match the characters exactly (e.g. "01/10/2021 12:00" and "dd/ww/yyyy hh:mm" will throw, but "01/ww/2021 12:00" and "dd/ww/yyyy hh:mm" does not).
Thrown when Format Template is null or empty (i.e. "") and the Text does not match the ISO 8601 Standard format, the default format of the Format Provider (e.g. "31/12/2021 00:00" and "dd/MM/yyyy").
PropertyEmptyException Thrown when Text is empty (i.e. "").
PropertyNullException Thrown when Text is null.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Format Template and Specifiers

Please note that changes to operating system date and time formats, could result in some of the examples above displaying different results.

For information about format templates and specifiers, please see Date and Time Formatting.

Null or Empty Format Template

If Format Template is not specified, null or empty (i.e. ""), the ISO 8601 Standard format will be used for the conversion (i.e. "yyyy-MM-ddTHH:mm:ss.fffffffzzz").

If the ISO 8601 Standard format fails, then the default template of the specified Format Provider will be used; if there is no specified Format Provider, then Invariant Culture rules will be used instead.

Null Format Provider

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

6.3.2.3 - Get Date Time

Get the current date time or parts of a date time (i.e. Year, Month, Day).

6.3.2.3.1 - Get Current Date Time

Gets the current Date Time.
Icon

Get Current Date Time

(Cortex.Blocks.DateAndTime.GetDateTime.GetCurrentDateTimeBlock)

Description

Gets the current Date Time.

Examples

Get the current Date Time

This example will get the current Date Time.

Properties

Property Value Notes
Date Time ($)DateTime, with no value ($)DateTime is a variable that will be set to a DateTimeOffset value

Result

Getting the current Date Time will result in the variable ($)DateTime being set to a DateTimeOffset representing the current Date Time (including a UTC time offset). Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-11-05T08:48:08.0307614+00:00"

Properties

Date Time

The current Date Time including a UTC time offset.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

6.3.2.3.2 - Get Date Time Component

Gets a component (e.g. Year, Month, Day) of a specified Date Time.
Icon

Get Date Time Component

(Cortex.Blocks.DateAndTime.GetDateTime.GetDateTimeComponentBlock)

Description

Gets a Component (e.g. Year, Month, Day) of the specified Date Time.

Component Type is used to specify which type of component to get.

For more information about values that can be specified for Component Type, please see DateTimeComponentType or the examples below.

Examples

LocalDateTime

This example will get the LocalDateTime of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

In this example assume that the local date and time is in the GMT time zone.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T00:05:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.LocalDateTime ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the LocalDateTime (GMT) of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to a DateTime value. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T10:00:00+00:00"

UtcDateTime

This example will get the UTCDateTime of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.UtcDateTime ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the UTCDateTime of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to a DateTime value. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T10:00:00Z"

Date

This example will get the Date component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Date ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Date component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to a DateTime value. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-12-31T00:00:00"

Time

This example will get the Time component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Time ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Time component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following TimePeriod value:

{
  "Years": 0,
  "Months": 0,
  "Days": 0,
  "Hours": 5,
  "Minutes": 0,
  "Seconds": 0,
  "Milliseconds": 0
}

Year

This example will get the Year component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Year ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Year component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

2021

Month

This example will get the Month component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Month ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Month component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

12

Day

This example will get the Day component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Day ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Day component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

31

Hour

This example will get the Hour component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Hour ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Hour component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

5

Minute

This example will get the Minute component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Minute ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Minute component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

0

Second

This example will get the Second component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Second ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Second component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

0

Millisecond

This example will get the Millisecond component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Millisecond ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Millisecond component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

0

Offset

This example will get the Offset component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.Offset ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the Offset component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following TimeSpan value with the following text representation:

"-5:00:00"

DayOfYear

This example will get the DayOfYear component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.DayOfYear ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the DayOfYear component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following Int32 value:

365

DayOfWeek

This example will get the DayOfWeek component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset).

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-12-31T05:00:00-05:00 ($)DateTime is a variable of type DateTimeOffset
Component Type ($)ComponentType, with value of DateTimeComponentType.DayOfWeek ($)DateTime is a variable of type DateTimeComponentType
Component ($)Component, with no value ($)Component is a variable that will be set to a dynamic value

Result

Getting the DayOfWeek component of a Date Time representing 5am on 31st December 2021 (with -5 UTC time offset), will result in the variable ($)Component being updated to the following DayOfWeek value:

DayOfWeek.Friday

Properties

Date Time

The Date Time to get the specified Component Type from.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Component Type

The Component Type to get from the Date Time.

For more information about values that can be specified for Component Type, please see DateTimeComponentType or the examples above.

Data Type DateTimeComponentType
Property Type Input
Is Advanced false
Default Editor Literal
Default Value LocalDateTime

Component

The Component from the Date Time.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Component with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Component Type is not one of the specified DateTimeComponentType types (e.g. (DateTimeComponentType)100).

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Why does the Component property return a dynamic data type?

The decision for Component to return a dynamic data type rather than an Object, was to avoid users having to cast the component to its correct type to be able to use all of its properties.

As a result, any issues with using the Component (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the variable specified for Component to its correct type when using it (e.g. for UtcDateTime component it could be case as follows: (DateTime)($)Component).

6.3.2.4 - Get Time Period

Get the time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) between two date times.

6.3.2.4.1 - Get Time Period Between Date Times

Gets the Time Period between two Date Times.
Icon

Get Time Period Between Date Times

(Cortex.Blocks.DateAndTime.GetTimePeriod.GetTimePeriodBetweenDateTimesBlock)

Description

Get the Time Period between the specified Start Date Time and End Date Time.

Examples

Get Time Period between Start Date Time and End Date Time

This example will get the Time Period between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Start Date Time ($)StartDateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)StartDateTime is a variable of type DateTimeOffset
End Date Time ($)EndDateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)EndDateTime is a variable of type DateTimeOffset
Time Period ($)TimePeriod, with no value ($)TimePeriod is a variable that will be set to a TimePeriod value

Result

Getting the Time Period between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00 will result in the variable ($)TimePeriod being updated to the following:

{
    "Years": 0, 
    "Months": 0, 
    "Days": 365, 
    "Hours": 0, 
    "Minutes": 0, 
    "Seconds": 0, 
    "Milliseconds": 0
}

Properties

Start Date Time

The Start Date Time to get the Time Period between.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)StartDateTime with no value

End Date Time

The End Date Time to get the Time Period between.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)EndDateTime with no value

Time Period

The Time Period between the Start Date Time and End Date Time.

Time Period can have positive and negative components where components are:

  • Years
  • Months
  • Days
  • Hours
  • Minutes
  • Seconds
  • Milliseconds

In this block, the Year and Month components are not used as they aren’t constant (i.e. Years can have different numbers of days depending upon whether it is a leap year or not, and months can have different numbers of days); instead Days will be used.

Time Period is calculated by subtracting Start Date Time from End Date Time; therefore if Start Date Time is less than End Date Time, the Time Period components will be positive, if it is equal they will be 0 and finally if it is greater than they will be negative.

For more information about Date and Time, please see Working with Date and Time.

Data Type TimePeriod
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TimePeriod with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Years and Months components not used

In this block, the Year and Month components are not used as they aren’t constant (i.e. Years can have different numbers of days depending upon whether it is a leap year or not, and months can have different numbers of days); instead Days will be used.

Start Date Time greater than End Date Time

Start Date Time can be greater than End Date Time; if this is the case the components of the Time Period will be negative.

6.3.2.5 - Is Date Time

Check if a date time is equal to another date time, before it, after it, or between two date times.

6.3.2.5.1 - Is Date Time After

Checks if a Date Time is after another Date Time.
Icon

Is Date Time After

(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeAfterBlock)

Description

Checks if a Date Time is after a given Date Time To Compare.

Examples

Date Time is after Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is after 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is After ($)DateTimeIsAfter, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is after 2021-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsAfter being updated to the following:

true

Date Time is before Date Time To Compare

This example will check if 2021-01-01T00:00:00+00:00 is after 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is After ($)DateTimeIsAfter, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2021-01-01T00:00:00+00:00 is after 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsAfter being updated to the following:

false

Date Time is equal to Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is after 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is After ($)DateTimeIsAfter, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is after 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsAfter being updated to the following:

false

Properties

Date Time

The Date Time to check is after Date Time To Compare.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Date Time To Compare

The Date Time to check if Date Time is after.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeToCompare with no value

Date Time Is After

The result of the is after check.

If Date Time is after Date Time To Compare, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeIsAfter with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

6.3.2.5.2 - Is Date Time Before

Checks if a Date Time is before another Date Time.
Icon

Is Date Time Before

(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeBeforeBlock)

Description

Checks if a Date Time is before a given Date Time To Compare.

Examples

Date Time is before Date Time To Compare

This example will check if 2021-01-01T00:00:00+00:00 is before 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Before ($)DateTimeIsBefore, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2021-01-01T00:00:00+00:00 is before 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsBefore being updated to the following:

true

Date Time is after Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is before 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Before ($)DateTimeIsBefore, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is before 2021-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsBefore being updated to the following:

false

Date Time is equal to Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is before 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Before ($)DateTimeIsBefore, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is before 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsBefore being updated to the following:

false

Properties

Date Time

The Date Time to check is before Date Time To Compare.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Date Time To Compare

The Date Time to check if Date Time is before.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeToCompare with no value

Date Time Is Before

The result of the is before check.

If Date Time is before Date Time To Compare, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeIsBefore with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

6.3.2.5.3 - Is Date Time Between

Checks if a Date Time is between two Date Times.
Icon

Is Date Time Between

(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeBetweenBlock)

Description

Checks if a Date Time is between the specified Start Date Time and End Date Time.

Examples

Date Time is between Start Date Time and End Date Time

This example will check if 2021-06-01T00:00:00+00:00 is between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-06-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Start Date Time ($)StartDateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)StartDateTime is a variable of type DateTimeOffset
End Date Time ($)EndDateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)EndDateTime is a variable of type DateTimeOffset
Date Time Is Between ($)DateTimeIsBetween, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2021-06-01T00:00:00+00:00 is between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsBetween being updated to the following:

true

Date Time is not between Start Date Time and End Date Time

This example will check if 2020-01-01T00:00:00+00:00 is between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2020-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Start Date Time ($)StartDateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)StartDateTime is a variable of type DateTimeOffset
End Date Time ($)EndDateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)EndDateTime is a variable of type DateTimeOffset
Date Time Is Between ($)DateTimeIsBetween, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2020-01-01T00:00:00+00:00 is between 2021-01-01T00:00:00+00:00 and 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsBetween being updated to the following:

false

Properties

Date Time

The Date Time to check is between Start Date Time and End Date Time.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Start Date Time

The Start Date Time to check against. This is inclusive, which means if Date Time is equal to it, it will be considered between.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)StartDateTime no value

End Date Time

The End Date Time to check against. This is inclusive, which means if Date Time is equal to it, it will be considered between.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)EndDateTime with no value

Date Time Is Between

The result of the is between check.

If Date Time is between (and including) the Start Date Time and End Date Time, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeIsBetween with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Start Date Time and End Date Time are inclusive

The Start Date Time and End Date Time properties are both inclusive, which means if Date Time is equal to either of them, it will be considered between.

Start Date Time greater than End Date Time

Start Date Time can be greater than End Date Time; as long as Date Time is between or equal to either of them the variable specified for Date Time Is Between will be set to true, otherwise it will be set to false.

6.3.2.5.4 - Is Date Time Equal

Checks if a Date Time is equal to another Date Time.
Icon

Is Date Time Equal

(Cortex.Blocks.DateAndTime.IsDateTime.IsDateTimeEqualBlock)

Description

Checks if a Date Time is equal to a given Date Time To Compare.

Examples

Date Time is equal to Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is equal to 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Equal ($)DateTimeIsEqual, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is equal 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsEqual being updated to the following:

true

Date Time is after Date Time To Compare

This example will check if 2022-01-01T00:00:00+00:00 is equal to 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Equal ($)DateTimeIsEqual, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2022-01-01T00:00:00+00:00 is equal to 2021-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsEqual being updated to the following:

false

Date Time is before Date Time To Compare

This example will check if 2021-01-01T00:00:00+00:00 is equal to 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Date Time To Compare ($)DateTimeToCompare, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTimeToCompare is a variable of type DateTimeOffset
Date Time Is Equal ($)DateTimeIsEqual, with no value ($)DateTime is a variable that will be set to a Boolean value

Result

Checking if 2021-01-01T00:00:00+00:00 is equal to 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTimeIsEqual being updated to the following:

false

Properties

Date Time

The Date Time to check is equal to Date Time To Compare.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Date Time To Compare

The Date Time to check if Date Time is equal to.

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeToCompare with no value

Date Time Is Equal

The result of the is equal check.

If Date Time is equal to Date Time To Compare, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)DateTimeIsEqual with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

6.3.2.6 - Subtract Time Period

Subtract a time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds) from a date time.

6.3.2.6.1 - Subtract Time Period

Subtracts a Time Period to from specified Date Time.
Icon

Subtract Time Period

(Cortex.Blocks.DateAndTime.SubtractTimePeriod.SubtractTimePeriodBlock)

Description

Subtracts a Time Period from the specified Date Time.

This block can subtract both positive and negative TimePeriod values.

Examples

Subtract a positive Time Period

This example will subtract 1 year from 2022-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2022-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Time Period ($)TimePeriod, with value of {"Years": 1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0} ($)TimePeriod is a variable of type TimePeriod

Result

Subtracting 1 year from 2022-01-01T00:00:00+00:00 will result in the variable ($)DateTime being updated. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2021-01-01T00:00:00+00:00"

Subtract a negative Time Period

This example will subtract -1 year from 2021-01-01T00:00:00+00:00.

Properties

Property Value Notes
Date Time ($)DateTime, with value of DateTimeOffset that has a text representation of 2021-01-01T00:00:00+00:00 ($)DateTime is a variable of type DateTimeOffset
Time Period ($)TimePeriod, with value of {"Years": -1, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 0, "Milliseconds": 0} ($)TimePeriod is a variable of type TimePeriod

Result

Subtracting -1 year from 2021-01-01T00:00:00+00:00 will result in 1 year being added and the variable ($)DateTime being updated. Its text representation will be in the ISO 8601 Standard, which can be seen below:

"2022-01-01T00:00:00+00:00"

Properties

Date Time

The Date Time to subtract the Time Period from.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type DateTimeOffset
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)DateTime with no value

Time Period

The Time Period to subtract from the Date Time.

Time Period can have positive and negative components where components are:

  • Years
  • Months
  • Days
  • Hours
  • Minutes
  • Seconds
  • Milliseconds

When subtracting a Time Period, the block will first subtract years, followed by months, days, hours, minutes, seconds and finally milliseconds.

When subtracting months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. subtracting one month from 2021-02-28T23:59:59+00:00 will equate to 2021-01-31T23:59:59+00:00).

For more information about Date and Time, please see Working with Date and Time.

Data Type TimePeriod
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Years: 0
Months: 0
Days: 0
Hours: 0
Minutes: 0
Seconds: 0
Milliseconds: 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when subtracting Time Period from Date Time will result in the Date Time being less than 0001-01-01T00:00:00+00:00. See Property Less Than Minimum Value.
Thrown when subtracting Time Period from Date Time will result in the Date Time being greater than 9999-12-31T23:59:59+00:00. See Property Greater Than Maximum Value.

Remarks

Dates and Time

The default text representation of Date and Time will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

For more information, please see Working with Date and Time.

Order of calculations

When subtracting a Time Period, the block will first subtract years, followed by months, days, hours, minutes, seconds and finally milliseconds.

Subtraction of Months

When subtracting months from the Date Time, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. subtracting one month from 2021-02-28T23:59:59+00:00 will equate to 2021-01-31T23:59:59+00:00).

Daylight Savings

This block copes with UTC time offsets but does not know anything about which time zone the Date Time represents; as a result it cannot take daylight savings into account as these are related to time zones rather than UTC time offsets.

6.3.3 - Decisions

Blocks related to making decisions and branching the path a flow execution takes.

6.3.3.1 - If Else

Perform if-else like conditional decision making.

6.3.3.1.1 - If Null Exit Bottom

Checks if a given value is null; if so the flow execution exits via the block’s bottom port, otherwise it exits via the right port.
Icon

If Null Exit Bottom

(Cortex.Blocks.Decisions.If.IfNullExitBottomBlock`1)

Description

Checks if a given Value is null; if so the flow execution exits via the block’s bottom port (green tick), otherwise it exits via the right port (red cross).

For information about null, please see Null and Nullable Types.

Examples

Value is null

This example will check if null is null.

Properties

Property Value Notes
Value ($)Value, with value null ($)Value is a variable of type String

Result

null is null, so the flow execution exits via the block’s bottom port (green tick).


Value is not null

This example will check if "The quick brown fox jumps over the lazy dog" is null.

Properties

Property Value Notes
Value ($)Value, with value "The quick brown fox jumps over the lazy dog" ($)Value is a variable of type String

Result

"The quick brown fox jumps over the lazy dog" is not null, so the flow execution exits via the block’s right port (red cross).


Properties

Value

The Value to check is null.

For information about null, please see Null and Nullable Types.

Data Type TValue
Property Type Input
Is Advanced false
Default Editor Variable
Default Value No value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNotNullableException Thrown when Value is given a non-nullable value type.

Remarks

Null and Nullable Types

For information about null, please see Null and Nullable Types.

6.3.3.1.2 - If Null Exit Right

Checks if a given value is null; if so the flow execution exits via the block’s right port, otherwise it exits via the bottom port.
Icon

If Null Exit Right

(Cortex.Blocks.Decisions.If.IfNullExitRightBlock`1)

Description

Checks if a given Value is null; if so the flow execution exits via the block’s right port (green tick), otherwise it exits via the bottom port (red cross).

For information about null, please see Null and Nullable Types.

Examples

Value is null

This example will check if null is null.

Properties

Property Value Notes
Value ($)Value, with value null ($)Value is a variable of type String

Result

null is null, so the flow execution exits via the block’s right port (green tick).


Value is not null

This example will check if "The quick brown fox jumps over the lazy dog" is null.

Properties

Property Value Notes
Value ($)Value, with value "The quick brown fox jumps over the lazy dog" ($)Value is a variable of type String

Result

"The quick brown fox jumps over the lazy dog" is not null, so the flow execution exits via the block’s bottom port (red cross).


Properties

Value

The Value to check is null.

For information about null, please see Null and Nullable Types.

Data Type TValue
Property Type Input
Is Advanced false
Default Editor Variable
Default Value No value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNotNullableException Thrown when Value is given a non-nullable value type.

Remarks

Null and Nullable Types

For information about null, please see Null and Nullable Types.

6.3.3.1.3 - If True Exit Bottom

Checks if a given value evaluates to true; if so the flow execution exits via the block’s bottom port, otherwise it exits via the right port.
Icon

If True Exit Bottom

(Cortex.Blocks.Decisions.If.IfTrueExitBottomBlock)

Description

Checks if a given Value evaluates to true; if so the flow execution exits via the block’s bottom port (green tick), otherwise it exits via the right port (red cross).

Examples

Value is true

This example will check if 1 + 1 == 2 evaluates to true or false.

Properties

Property Value Notes
Value ($)Value, with value 1 + 1 == 2 ($)Value is a variable whose value evaluates to type Boolean

Result

1 + 1 == 2 is true, so the flow execution exits via the block’s bottom port (green tick).


Value is false

This example will check if 1 + 1 == 1 evaluates to true or false.

Properties

Property Value Notes
Value ($)Value, with value 1 + 1 == 1 ($)Value is a variable whose value evaluates to type Boolean

Result

1 + 1 == 1 is false, so the flow execution exits via the block’s right port (red cross).


Properties

Value

The Value to check evaluates to true or false.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Variable
Default Value No value

Exceptions

No exceptions are thrown by the block.

Remarks

No remarks for the block.

6.3.3.1.4 - If True Exit Right

Checks if a given value evaluates to true; if so the flow execution exits via the block’s right port, otherwise it exits via the bottom port.
Icon

If True Exit Right

(Cortex.Blocks.Decisions.If.IfTrueExitRightBlock)

Description

Checks if a given Value evaluates to true; if so the flow execution exits via the block’s right port (green tick), otherwise it exits via the bottom port (red cross).

Examples

Value is true

This example will check if 1 + 1 == 2 evaluates to true or false.

Properties

Property Value Notes
Value ($)Value, with value 1 + 1 == 2 ($)Value is a variable whose value evaluates to type Boolean

Result

1 + 1 == 2 is true, so the flow execution exits via the block’s right port (green tick).


Value is false

This example will check if 1 + 1 == 1 evaluates to true or false.

Properties

Property Value Notes
Value ($)Value, with value 1 + 1 == 1 ($)Value is a variable whose value evaluates to type Boolean

Result

1 + 1 == 1 is false, so the flow execution exits via the block’s bottom port (red cross).


Properties

Value

The Value to check evaluates to true or false.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Variable
Default Value No value

Exceptions

No exceptions are thrown by the block.

Remarks

No remarks for the block.

6.3.4 - Dictionaries

Blocks related to working with Dictionaries.

6.3.4.1 - Add Item(s)

Add an item or multiple items to a dictionary.

6.3.4.1.1 - Add Item With Key

Adds an item to a Dictionary with the specified key.
Icon

Add Item With Key

(Cortex.Blocks.Dictionaries.AddItem.AddItemWithKeyBlock`3)

Description

Adds an Item to a Dictionary with the specified Key.

Examples

Add an Item to an empty Dictionary

This example will add 1 to {} with a key of "Key1".

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Item ($)Item, with value 1 ($)Item is a variable of type Int32

Result

Adding 1 to {} with a key of "Key1" results in the variable ($)Dictionary being updated to the following:

{"Key1" : 1}

Add an Item to a Dictionary

This example will add 2 to {"Key1" : 1} with a key of "Key2".

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key2" ($)Key is a variable of type String
Item ($)Item, with value 2 ($)Item is a variable of type Int32

Result

Adding 2 to {"Key1" : 1} with a key of "Key2" results in the variable ($)Dictionary being updated to the following:

{"Key1" : 1, "Key2" : 2}

Properties

Dictionary

The Dictionary where the Item is added with the specified Key.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key to add the Item with.

Keys cannot be null and must be unique within a dictionary, as they are used to lookup the item they correspond to.

For information and examples of how it is determined whether a key is already present, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Item

The Item to be added to the Dictionary with the specified Key.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when Item is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
KeyPresentException Thrown when an item with the specified Key is already present.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.2 - Contains Item(s)

Check if an item or multiple items are contained in a dictionary.

6.3.4.2.1 - Contains Item With Key

Checks if a Dictionary contains at least one item with the specified key.
Icon

Contains Item With Key

(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithKeyBlock`3)

Description

Checks if Dictionary contains at least one item with the specified Key.

Examples

Dictionary contains item with Key

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with the key "Key1".

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains one item with the key Key1. Therefore, the variable ($)ContainsItem will be updated to the following:

true

Dictionary does not contain item with Key

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with the key "Key10".

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key10" ($)Key is a variable of type String
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} does not contain any items with the key "Key10". Therefore, the variable ($)ContainsItem will be updated to the following:

false

Properties

Dictionary

The Dictionary to check whether it contains at least one item with the specified Key.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key to check for matching items.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Item

The result of the contains item check.

If Dictionary contains at least one item with the specified Key, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItem with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Contains Item property is set to false.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.2.2 - Contains Item With Key And Value

Checks if a Dictionary contains at least one item with the specified key and matching the specified value.
Icon

Contains Item With Key And Value

(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithKeyAndValueBlock`3)

Description

Checks if Dictionary contains at least one item with the specified Key and matching the specified Value.

Examples

Dictionary contains item with Key and Value

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with the key "Key1" and value 1.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains one item with the key Key1 and value 1. Therefore, the variable ($)ContainsItem will be updated to the following:

true

Dictionary does not contain item with Key and Value

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with the key "Key1" and value 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Value ($)Value, with value 10 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains one item with the key "Key1", but its value is not 10. Therefore, the variable ($)ContainsItem will be updated to the following:

false

Properties

Dictionary

The Dictionary to check whether it contains at least one item with the specified Key and matching Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key to check for matching items.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Value

The Value to check for matching items.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Item

The result of the contains item check.

If Dictionary contains at least one item with the specified Key and matching Value, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItem with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Contains Item property is set to false.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.2.3 - Contains Item With Value

Checks if a Dictionary contains at least one item matching the specified value.
Icon

Contains Item With Value

(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemWithValueBlock`3)

Description

Checks if Dictionary contains at least one item matching Value.

Examples

Dictionary contains item with Value

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains the value 1.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains two items with the value 1. Therefore, the variable ($)ContainsItem will be updated to the following:

true

Dictionary does not contain item with Value

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains the value 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 10 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} does not contain any items with the value 10. Therefore, the variable ($)ContainsItem will be updated to the following:

false

Properties

Dictionary

The Dictionary to check whether it contains at least one item matching the specified Value.

Items are considered matching if they have the specified Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value to check for matching items.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Item

The result of the contains item check.

If Dictionary contains at least one item matching the specified Value, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItem with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Contains Item property is set to false.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.2.4 - Contains Items With Keys

Checks if a Dictionary contains at least one item with each of the specified keys.
Icon

Contains Items With Keys

(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemsWithKeysBlock`3)

Description

Checks if Dictionary contains at least one item with each of the specified Keys.

Examples

Dictionary contains items with Keys

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with each of the keys in ["Key1", "Key2", "Key3"].

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Keys ($)Keys, with value ["Key1", "Key2", "Key3"] ($)Keys is a variable of type IEnumerable<String>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item matching each of the values in ["Key1", "Key2", "Key3"]; it contains one item with the key "Key1", one item with the key "Key2" and one item with the key "Key3". Therefore, the variable ($)ContainsItems will be updated to the following:

true

Dictionary does not contain items with Keys

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item with each of the keys in ["Key1", "Key2", "Key3", "Key10"].

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Keys ($)Keys, with value ["Key1", "Key2", "Key3", "Key10"] ($)Keys is a variable of type IEnumerable<String>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} does not contain at least one item matching each of the values in ["Key1", "Key2", "Key3"]; it contains one item with the key "Key1", one item with the key "Key2" and one item with the key "Key3", but no items with the key "Key10". Therefore, the variable ($)ContainsItems will be updated to the following:

false

Properties

Dictionary

The Dictionary to check whether it contains at least one item with each of the specified Keys.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Keys

The Keys to check for matching items.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type IEnumerable<TKey>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Items

The result of the contains items check.

If Dictionary contains at least one item with each of the specified Keys, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItems with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentNullException Thrown when any key in Keys is null
PropertyNullException Thrown when Dictionary or Keys are null.

Remarks

Key Equality

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Contains Items property is set to false.

Empty Keys

If Keys is empty (i.e. []), the variable specified in the Contains Items property is set to false.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.2.5 - Contains Items With Values

Checks if a Dictionary contains at least one item matching each of the specified values.
Icon

Contains Items With Values

(Cortex.Blocks.Dictionaries.ContainsItem.ContainsItemsWithValuesBlock`3)

Description

Checks if Dictionary contains at least one item matching each of the specified Values.

Examples

Dictionary contains items with Values

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item matching each of the values in [1, 2, 3].

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Values ($)Values, with value [1, 2, 3] ($)Values is a variable of type IEnumerable<Int32>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item matching each of the values in [1, 2, 3]; it contains two items with the value 1, two items with the value 2 and two items with the value 3. Therefore, the variable ($)ContainsItems will be updated to the following:

true

Dictionary does not contain items with Values

This example will check whether {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} contains at least one item matching each of the values in [1, 2, 3, 10].

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Values ($)Values, with value [1, 2, 3, 10] ($)Values is a variable of type IEnumerable<Int32>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

{"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} does not contain at least one item matching each of the values in [1, 2, 3, 10]; it contains two items with the value 1, two items with the value 2 and two items with the value 3, but no items with the value 10. Therefore, the variable ($)ContainsItems will be updated to the following:

false

Properties

Dictionary

The Dictionary to check whether it contains at least one item matching each of the specified Values.

Items are considered matching if they have a value matching one of the specified Values.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Values

The Values to check for matching items.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Items

The result of the contains items check.

If Dictionary contains at least one item matching each of the specified Values, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItems with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary or Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Contains Items property is set to false.

Empty Values

If Values is empty (i.e. []), the variable specified in the Contains Items property is set to false.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.3 - Get Count(s) of Items

Get the count(s) of items in a dictionary.

6.3.4.3.1 - Get Count Of All Items

Gets the count of all items in a Dictionary.
Icon

Get Count Of All Items

(Cortex.Blocks.Dictionaries.GetCount.GetCountOfAllItemsBlock`3)

Description

Gets the Count of all items in a Dictionary.

Examples

Get Count of all items in a Dictionary

This example will get the count of all items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Count ($)Count, with no value ($)Count is a variable that will be set to an Int32 value

Result

Getting the count of all items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Count being updated to the following:

6

Properties

Dictionary

The Dictionary to get the Count of all items for.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Count

The Count of all items in Dictionary.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Count with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary is null.

Remarks

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Count property is set to 0.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.3.2 - Get Count Of Items With Value

Gets the count of items in a Dictionary with the specified value.
Icon

Get Count Of Items With Value

(Cortex.Blocks.Dictionaries.GetCount.GetCountOfItemsWithValueBlock`3)

Description

Gets the Count of items in a Dictionary with the specified Value.

Examples

Get Count of items in a Dictionary with a Value

This example will get the count of items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} with the value 1.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Count ($)Count, with no value ($)Count is a variable that will be set to an Int32 value

Result

Getting the count of items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} with the value 1 results in the variable ($)Count being updated to the following:

2

Properties

Dictionary

The Dictionary to get the Count of items with the specified Value for.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value items must match to be included in the Count.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Count

The Count of items in Dictionary with the specified Value.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Count with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}), the variable specified in the Count property is set to 0.

No items matching Value

If Dictionary does not contain items matching the specified Value, the variable specified in the Count property is set to 0.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.3.3 - Get Counts Of Items With Values

Gets the counts of items in a Dictionary matching each of the specified values.
Icon

Get Counts Of Items With Values

(Cortex.Blocks.Dictionaries.GetCount.GetCountsOfItemsWithValuesBlock`3)

Description

Gets the Counts of items in a Dictionary matching each of the specified Values.

Examples

Get Counts of items in a Dictionary matching each of the Values

This example will get the counts of items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} matching each of the values [1, 2, 3].

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Values ($)Values, with value [1, 2, 3] ($)Values is a variable of type IEnumerable<Int32>
Counts ($)Counts, with no value ($)Counts is a variable that will be set to an IList<Int32> value

Result

Getting the counts of items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} matching each of the values [1, 2, 3] results in the variable ($)Counts being updated to the following:

[2, 2, 2]

The counts of items matching each value are added to ($)Counts at the same index the value is in ($)Values. In this example, there are two items matching the first value 1, two items matching the second value 2 and two items matching the third value 3, resulting in ($)Counts being set to [2, 2, 2].


Properties

Dictionary

The Dictionary to get the Counts of items matching each of the specified Values for.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Values

The Values items must match to be included in the Counts.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Counts

The Counts of items in Dictionary matching each of the specified Values.

For each value in Values, Counts will have a corresponding item whose value is the count of items in Dictionary matching the value.

I.e. The count of items matching the first value in Values will be saved as the first item in Counts; the count of items matching the second value in Values will be saved as the second item in Counts etc.

Data Type IList<Int32>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Counts with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary or Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Values

If Values is empty (i.e. []), the variable specified in the Counts property is set to empty (i.e. []).

No items matching a specified value in Values

If Dictionary does not contain items matching one of the specified Values, 0 is written to the corresponding item in Counts for that value.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.4 - Get Item(s)

Get an item or multiple items from a dictionary.

6.3.4.4.1 - Get All Items

Gets all items from a Dictionary.
Icon

Get All Items

(Cortex.Blocks.Dictionaries.GetItem.GetAllItemsBlock`3)

Description

Get all Items from a Dictionary.

Examples

Get all items from a Dictionary

This example will get all items in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<Int32>

Result

Getting all items from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Items being updated to the following:

[1, 2, 3, 3, 2, 1]

Properties

Dictionary

The Dictionary to get all Items from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Items

The Items in the Dictionary.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary is null.

Remarks

Empty Dictionary

If Dictionary is empty (i.e. {}) the variable specified in the Items property is set to an empty IList<TItem> (i.e. []).

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.4.2 - Get Item With Key

Gets the specified occurrence of an item with the given key from a Dictionary.
Icon

Get Item With Key

(Cortex.Blocks.Dictionaries.GetItem.GetItemWithKeyBlock`3)

Description

Gets the specified Occurrence of an Item with the given Key from a Dictionary.

Examples

Get the first Occurrence of an Item with a Key from a Dictionary

This example will attempt to get the first occurrence of an item with the key "Key1" from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. Int32)

Result

An Occurrence of 1 means get the first occurrence; 2 means second etc.

Attempting to get the first occurrence of an item with the key "Key1" from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Item being updated to the following:

1

Get the last Occurrence of an Item with a Key from a Dictionary

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to get an occurrence of item with that key.

This example will illustrate this, by attempting to get the last occurrence of an item with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. Int32)

Result

An Occurrence of -1 means get the last occurrence; -2 means second last etc.

Attempting to get the last occurrence of an item with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} results in the variable ($)Item being updated to the following:

10

Properties

Dictionary

The Dictionary to get the specified Occurrence of Item with the given Key from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the Item to get must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching Item to get from the Dictionary.

Items are considered matching if they have the specified Key.

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Item

The specified Occurrence of Item with the given Key from Dictionary.

Data Type TItem
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Item with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
KeyNotPresentException Thrown when the Key is not present in the Dictionary.
OccurrenceNotPresentException Thrown when the specified Occurrence of Item with the given Key is not present in the Dictionary.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Occurrences

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.4.3 - Get Items With Key

Gets all items with the given key from a Dictionary.
Icon

Get Items With Key

(Cortex.Blocks.Dictionaries.GetItem.GetItemsWithKeyBlock`3)

Description

Gets all Items with the given Key from a Dictionary.

Examples

Get all Items with a Key from a Dictionary

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to get all items with that key.

This example will illustrate this, by attempting to get all items with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<Int32>

Result

Attempting to get all items with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10} results in the variable ($)Items being updated to the following:

[1, 10]

Properties

Dictionary

The Dictionary to get all Items with the given Key from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the Items to get must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Items

All Items with the given Key in Dictionary.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
KeyNotPresentException Thrown when the Key is not present in the Dictionary.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.5 - Get Key(s)

Get a key or multiple keys from a dictionary.

6.3.4.5.1 - Get All Keys

Gets all keys from a Dictionary.
Icon

Get All Keys

(Cortex.Blocks.Dictionaries.GetKey.GetAllKeysBlock`3)

Description

Get all Keys from a Dictionary.

Examples

Get all keys from a Dictionary

This example will get all keys in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Keys ($)Keys, with no value ($)Keys is a variable that will be set to an IList<String>

Result

Getting all keys from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Keys being updated to the following:

["Key1", "Key2", "Key3", "Key4", "Key5", "Key6"]

Properties

Dictionary

The Dictionary to get all Keys from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Keys

The Keys in the Dictionary.

Data Type IList<TKey>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Keys with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Dictionary is null.

Remarks

Empty Dictionary

If Dictionary is empty (i.e. {}) the variable specified in the Keys property is set to an empty IList<TKey> (i.e. []).

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6 - Remove Item(s)

Remove an item or multiple items from a dictionary.

6.3.4.6.1 - Remove All Items

Removes all items from a Dictionary.
Icon

Remove All Items

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveAllItemsBlock`3)

Description

Removes all items from a Dictionary.

Examples

Remove all items from an empty Dictionary

This example will attempt to remove all items from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>

Result

Attempting to remove all items from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove all items from a Dictionary

This example will remove all items from {"Key1" : 1, "Key2" : 2}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2} ($)Dictionary is a variable of type IDictionary<String, Int32>

Result

Removing all items from {"Key1" : 1, "Key2" : 2} results in the variable ($)Dictionary being updated to the following:

{}

Properties

Dictionary

The Dictionary where all items are removed from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor [Variable][]
Default Value ($)Dictionary with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
PropertyNullException Thrown when Dictionary is null.

Remarks

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.2 - Remove Item With Key

Removes the specified occurrence of an item with the given key from a Dictionary.
Icon

Remove Item With Key

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemWithKeyBlock`3)

Description

Removes the specified Occurrence of an item with the given Key from a Dictionary.

Examples

Remove the first Occurrence of an item with a Key from an empty Dictionary

This example will attempt to remove the first occurrence of an item with the key "Key1" from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

Attempting to remove the first occurrence of an item with the key "Key1" from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove the first Occurrence of an item with a Key from a Dictionary

This example will attempt to remove the first occurrence of an item with the key "Key1" from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means remove the first occurrence; 2 means second etc.

Attempting to remove the first occurrence of an item with the key "Key1" from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}

Remove the last Occurrence of an item with a Key from a Dictionary

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to remove any occurrence of item with that key.

This example will illustrate this, by attempting to remove the last occurrence of an item with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1 means remove the last occurrence; -2 means second last etc.

Attempting to remove the last occurrence of an item with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} results in the variable ($)Dictionary being updated to the following:

{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2}

Properties

Dictionary

The Dictionary to remove the specified Occurrence of item with the given Key from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the item to remove must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to remove from the Dictionary.

Items are considered matching if they have the specified Key.

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Occurrences

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

No items with given Key, or Occurrence is not present

If Dictionary does not contain items with the given Key or the specified Occurrence is not present, there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.3 - Remove Item With Value

Removes the specified occurrence of an item matching a value from a Dictionary.
Icon

Remove Item With Value

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemWithValueBlock`3)

Description

Removes the specified Occurrence of an item matching a Value from a Dictionary.

Examples

Remove the first Occurrence of an item matching a Value from an empty Dictionary

This example will attempt to remove the first occurrence of an item matching the value 1 from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

Attempting to remove the first occurrence of an item matching the value 1 from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove the first Occurrence of an item matching a Value from a Dictionary

This example will attempt to remove the first occurrence of an item matching the value 1 from {"Key1" : 1, "Key2" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means remove the first occurrence; 2 means second etc.

Attempting to remove the first occurrence of an item matching the value 1 from {"Key1" : 1, "Key2" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key2" : 1}

Remove the last Occurrence of an item matching a Value from a Dictionary

This example will attempt to remove the last occurrence of an item matching the value 1 from {"Key1" : 1, "Key2" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1, means remove the last occurrence; -2 means second last etc.

Attempting to remove the last occurrence of an item matching the value 1 from {"Key1" : 1, "Key2" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key1" : 1}

Properties

Dictionary

The Dictionary to remove the specified Occurrence of matching item from.

Items are considered matching if they have the specified Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value the item to remove must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to remove from the Dictionary.

Items are considered matching if they have the specified Value.

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Occurrences

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

No items matching Value, or Occurrence is not present

If Dictionary does not contain items matching the specified Value or the specified Occurrence is not present, there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.4 - Remove Items With Key

Removes all items with the given key from a Dictionary.
Icon

Remove Items With Key

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKeyBlock`3)

Description

Removes all items with the given Key from a Dictionary.

Examples

Remove all items with a Key from an empty Dictionary

This example will attempt to remove all items with the key "Key1" from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Key ($)Key, with value "Key1" ($)Key is a variable of type String

Result

Attempting to remove all items with the key "Key1" from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove all items with a Key from a Dictionary

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to remove all items with that key.

This example will illustrate this, by attempting to remove all items with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>

Result

Attempting to remove all items with the key [1] from {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} results in the variable ($)Dictionary being updated to the following:

{[2] : 2, [3] : 3, [3] : 3, [2] : 2}

Properties

Dictionary

The Dictionary to remove all items with the given Key from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the items to remove must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

No items with given Key

If Dictionary does not contain items with the given Key there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.5 - Remove Items With Keys

Removes all items with any of the given keys from a Dictionary.
Icon

Remove Items With Keys

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithKeysBlock`3)

Description

Removes all items with any of the given Keys from a Dictionary.

Examples

Remove all items with any of the given Keys from an empty Dictionary

This example will attempt to remove all items with any of the given keys in ["Key1", "Key2"] from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Keys ($)Keys, with value ["Key1", "Key2"] ($)Keys is a variable of type IDictionary<String>

Result

Attempting to remove all items with any of the given keys in ["Key1", "Key2"] from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove all items with any of the given Keys from a Dictionary

This example will attempt to remove all items with any of the given keys in ["Key1", "Key2"] from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<String, Int32>
Keys ($)Keys, with value ["Key1", "Key2"] ($)Keys is a variable of type IDictionary<String>

Result

Attempting to remove all items with any of the given keys in ["Key1", "Key2"] from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}

Properties

Dictionary

The Dictionary to remove all items with any of the given Keys from.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Keys

The Keys the items to remove must have one of.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type IEnumerable<TKey>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentNullException Thrown when any key in Keys is null
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
PropertyNullException Thrown when Dictionary or Keys are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

Empty Keys

If Keys is empty (i.e. []) there are no keys to match, therefore nothing can be removed and no operation is performed.

No items with one of the given Keys

If Dictionary does not contain items with one of the given Keys, there is nothing to remove for that key.

No items with any of the given Keys

If Dictionary does not contain items with any of the given Keys there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.6 - Remove Items With Value

Removes all items matching a value from a Dictionary.
Icon

Remove Items With Value

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValueBlock`3)

Description

Removes all items matching a Value from a Dictionary.

Examples

Remove all items matching a Value from an empty Dictionary

This example will attempt to remove all items matching the value 1 from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Value ($)Value, with value 1 ($)Value is a variable of type Int32

Result

Attempting to remove all items matching the value 1 from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove all items matching a Value from a Dictionary

This example will attempt to remove all items matching the value 1 from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32

Result

Attempting to remove all items matching the value 1 from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2}

Properties

Dictionary

The Dictionary to remove all matching items from.

Items are considered matching if they have the specified Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value the items to remove must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

No items matching Value

If Dictionary does not contain items matching the specified Value, there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.6.7 - Remove Items With Values

Removes all items matching one of the specified values from a Dictionary.
Icon

Remove Items With Values

(Cortex.Blocks.Dictionaries.RemoveItem.RemoveItemsWithValuesBlock`3)

Description

Removes all items matching one of the specified Values from a Dictionary.

Examples

Remove all items matching one of the specified Values from an empty Dictionary

This example will attempt to remove all items matching one of the values [1, 2] from {}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {} ($)Dictionary is a variable of type IDictionary<dynamic, dynamic>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>

Result

Attempting to remove all items matching one of the values [1, 2] from {} results in no operation, as there is nothing to remove. Therefore, the variable ($)Dictionary remains:

{}

Remove all items matching one of the specified Values from a Dictionary

This example will attempt to remove all items matching one of the values [1, 2] from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>

Result

Attempting to remove all items matching one of the values [1, 2] from {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} results in the variable ($)Dictionary being updated to the following:

{"Key3" : 3, "Key4" : 3}

Properties

Dictionary

The Dictionary to remove all matching items from.

Items are considered matching if they have one of the specified Values.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Values

The Values the items to remove must match one of.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
PropertyNullException Thrown when Dictionary or Values is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to remove, so no operation is performed.

Empty Values

If Values is empty (i.e. []) there are no values to match, therefore nothing can be removed and no operation is performed.

No items matching a specified value in Values

If Dictionary does not contain items matching one of the specified Values, there is nothing to remove for that value.

No items matching Values

If Dictionary does not contain items matching any of the specified Values, there is nothing to remove, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7 - Set Item(s)

Set an item or multiple items in a dictionary to a new value.

6.3.4.7.1 - Set All Items

Sets all items in a Dictionary to a new value.
Icon

Set All Items

(Cortex.Blocks.Dictionaries.SetItem.SetAllItemsBlock`3)

Description

Sets all items in a Dictionary to a New Value.

Examples

Set all items in a Dictionary to a New Value

This example will set all items in {"Key1" : 1, "Key2" : 2} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2} ($)Dictionary is a variable of type IDictionary<String, Int32>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32

Result

Setting all items in {"Key1" : 1, "Key2" : 2} to 10 results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 10}

Properties

Dictionary

The Dictionary to set all items in.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

New Value

The New Value to set all items in Dictionary to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when New Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to set, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.2 - Set Item With Key

Sets the specified occurrence of an item with the given key in a Dictionary to a new value.
Icon

Set Item With Key

(Cortex.Blocks.Dictionaries.SetItem.SetItemWithKeyBlock`3)

Description

Sets the specified Occurrence of an item with the given Key in a Dictionary to a New Value.

Examples

Set the first Occurrence of an item with a Key in a Dictionary to a New Value

This example will attempt to set the first occurrence of an item with the key "Key1" in {"Key1" : 1, "Key2" : 2} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2} ($)Dictionary is a variable of type IDictionary<String, Int32>
Key ($)Key, with value "Key1" ($)Key is a variable of type String
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means set the first occurrence; 2 means second etc.

Attempting to set the first occurrence of an item with the key "Key1" in {"Key1" : 1, "Key2" : 2} to 10 results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 1}

Set the last Occurrence of an item with a Key in a Dictionary to a New Value

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to set an occurrence of item with that key.

This example will illustrate this, by attempting to set the last occurrence of an item with the key [1] in {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1, means set the last occurrence; -2 means second last etc.

Attempting to set the last occurrence of an item with the key [1] in {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} to 10 results in the variable ($)Dictionary being updated to the following:

{[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}

Properties

Dictionary

The Dictionary to set the specified Occurrence of item with the given Key in.

Items are considered matching if they have the specified Key.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the item to set must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set the specified Occurrence of item with the given Key in Dictionary to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of item with the given Key to set in the Dictionary.

Items are considered matching if they have the specified Key.

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when New Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
KeyNotPresentException Thrown when the Key is not present in the Dictionary.
OccurrenceNotPresentException Thrown when the specified Occurrence of item with the given Key is not present in the Dictionary.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Occurrences

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.3 - Set Item With Value

Sets the specified occurrence of an item matching a value in a Dictionary to a new value.
Icon

Set Item With Value

(Cortex.Blocks.Dictionaries.SetItem.SetItemWithValueBlock`3)

Description

Sets the specified Occurrence of an item matching a Value in a Dictionary to a New Value.

Examples

Set the first Occurrence of an item matching a Value in a Dictionary to a New Value

This example will attempt to set the first occurrence of an item matching the value 1 in {"Key1" : 1, "Key2" : 1} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means set the first occurrence; 2 means second etc.

Attempting to set the first occurrence of an item matching the value 1 in {"Key1" : 1, "Key2" : 1} to 10 results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 1}

Set the last Occurrence of an item matching a Value in a Dictionary to a New Value

This example will attempt to set the last occurrence of an item matching the value 1 in {"Key1" : 1, "Key2" : 1} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1, means set the last occurrence; -2 means second last etc.

Attempting to set the last occurrence of an item matching the value 1 in {"Key1" : 1, "Key2" : 1} to 10 results in the variable ($)Dictionary being updated to the following:

{"Key1" : 1, "Key2" : 10}

Properties

Dictionary

The Dictionary to set the specified Occurrence of matching item in.

Items are considered matching if they have the specified Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value the item to set must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set the specified Occurrence of matching item in Dictionary to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to set in the Dictionary.

Items are considered matching if they have the specified Value.

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when Value or New Value are null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Occurrences

Unlike lists, dictionaries do not have a defined order. This means the nth occurrence is determined by the underlying Microsoft .Net implementation; this is not published and could change if the algorithm were to change.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to set, so no operation is performed.

No items matching Value, or Occurrence is not present

If Dictionary does not contain items matching the specified Value or the specified Occurrence is not present, there is nothing to set, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.4 - Set Items With Key

Sets all items with the given key in a Dictionary to a new value.
Icon

Set Items With Key

(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithKeyBlock`3)

Description

Sets all items with the given Key in a Dictionary to a New Value.

Examples

Sets all items with a Key in a Dictionary to a New Value

Typically keys are simple data types such as String, Int32, Boolean, and for these a dictionary cannot the same key value more than once. This is due to how the data type’s object equality is implemented (two items are considered equal if they have the same value rather than being the same object reference).

However, other data types such as IList<Int32> can also be used as keys. For these data types, object equality only considers two items equal if they are the same reference; it does not care about whether they have the same value. Therefore, it is possible to have the same key value more than once, and as a result you should be able to set all items with that key.

This example will illustrate this, by attempting to set all items with the key [1] in {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} ($)Dictionary is a variable of type IDictionary<IList<Int32>, Int32>
Key ($)Key, with value [1] ($)Key is a variable of type IList<Int32>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32

Result

Attempting to set all items with the key [1] in {[1] : 1, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 1} to 10 results in the variable ($)Dictionary being updated to the following:

{[1] : 10, [2] : 2, [3] : 3, [3] : 3, [2] : 2, [1] : 10}

Properties

Dictionary

The Dictionary to set all items with the given Key in.

Items are considered matching if they have the specified Key.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Key

The Key the items to set must have.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

For information about what a key is, please see Keys.

Data Type TKey
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set all items with the given Key in Dictionary to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when New Value is null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
KeyNotPresentException Thrown when the Key is not present in the Dictionary.
PropertyNullException Thrown when Dictionary or Key are null.

Remarks

Key Equality

For information and examples of how it is determined whether a key is already present, please see Object Equality.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.5 - Set Items With Keys

Sets all items with any of the given keys in a Dictionary to new values.
Icon

Set Items With Keys

(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithKeysBlock`3)

Description

Sets all items with any of the given Keys in a Dictionary to New Values.

Examples

Set all items with any of the given Keys in a Dictionary to New Values

This example will attempt to set all items with any of the keys ["Key1", "Key2"] in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to [10, 20] respectively.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Keys ($)Keys, with value ["Key1", "Key2"] ($)Keys is a variable of type IEnumerable<String>
NewValues ($)NewValues, with value [10, 20] ($)NewValues is a variable of type IEnumerable<Int32>

Result

Attempting to set all items with any of the keys ["Key1", "Key2"] in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to [10, 20] respectively, results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 20, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1}

Properties

Dictionary

The Dictionary to set all matching items in.

Items are considered matching if they have any of the specified Keys.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Keys

The Keys the items to set must have one of.

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

Data Type IEnumerable<TKey>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Values

The New Values to set the items with the corresponding Keys in Dictionary to.

The number of items in New Values must match the number of items in Keys.

Dictionary items with the first key in Keys will be set to the first value in New Values; Dictionary items with the second key in Keys will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentNullException Thrown when any key in Keys is null
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
KeysNotPresentException Thrown when any key in the Keys is not present in the Dictionary.
PropertyItemCountException Thrown when the count of items in Keys and the count of items in New Values are not the same, or neither contain any items.
PropertyNullException Thrown when Dictionary or Keys or New Values are null.

Remarks

Key Equality

For information and examples of how it is determined whether an item has a specified key, please see Object Equality.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.6 - Set Items With Value

Sets all items matching a value in a Dictionary to a new value.
Icon

Set Items With Value

(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithValueBlock`3)

Description

Sets all items matching a Value in a Dictionary to a New Value.

Examples

Set all items matching a Value in a Dictionary to a New Value

This example will attempt to set all items matching the value 1 in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to 10.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32

Result

Attempting to set all items matching the value 1 in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to 10 results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 10}

Properties

Dictionary

The Dictionary to set all matching items in.

Items are considered matching if they have the specified Value.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Value

The Value the items to set must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set all matching items in Dictionary to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
InvalidPropertyValueException Thrown when Value or New Value are null and Dictionary only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when Dictionary is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to set, so no operation is performed.

No items matching Value

If Dictionary does not contain items matching the specified Value, there is nothing to set, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.4.7.7 - Set Items With Values

Sets all items matching one of the specified values in a Dictionary to new values.
Icon

Set Items With Values

(Cortex.Blocks.Dictionaries.SetItem.SetItemsWithValuesBlock`3)

Description

Set all items matching one of the specified Values in a Dictionary to New Values.

Examples

Set all items matching one of the specified Values in a Dictionary to New Values

This example will attempt to set all items matching one of the values [1, 2] in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to [10, 20] respectively.

Properties

Property Value Notes
Dictionary ($)Dictionary, with value {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} ($)Dictionary is a variable of type IDictionary<String, Int32>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>
NewValues ($)NewValues, with value [10, 20] ($)NewValues is a variable of type IEnumerable<Int32>

Result

Attempting to set all items matching one of the values [1, 2] in {"Key1" : 1, "Key2" : 2, "Key3" : 3, "Key4" : 3, "Key5" : 2, "Key6" : 1} to [10, 20] respectively, results in the variable ($)Dictionary being updated to the following:

{"Key1" : 10, "Key2" : 20, "Key3" : 3, "Key4" : 3, "Key5" : 20, "Key6" : 10}

Properties

Dictionary

The Dictionary to set all matching items in.

Items are considered matching if they have one of the specified Values.

Dictionary can be any IDictionary<TKey, TItem>, where TKey represents the type of keys used to lookup items in the Dictionary, and TItem represents the type of items in the Dictionary.

Data Type IDictionary<TKey, TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Dictionary with no value

Values

The Values the items to set must match one of.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Values

The New Values to set the items matching the corresponding Values in Dictionary to.

The number of items in New Values must match the number of items in Values.

Dictionary items matching the first value in Values will be set to the first value in New Values; Dictionary items matching the second value in Values will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyDictionaryException Thrown when Dictionary is read-only.
DuplicateValueException Thrown when Values contains duplicate values.
PropertyItemCountException Thrown when the count of items in Values and the count of items in New Values are not the same, or neither contain any items.
PropertyNullException Thrown when Dictionary or Values or New Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Dictionary

If Dictionary is empty (i.e. {}) there is nothing to set, so no operation is performed.

No items matching a specified value in Values

If Dictionary does not contain items matching one of the specified Values, there is nothing to set for that value.

No items matching Values

If Dictionary does not contain items matching any of the specified Values, there is nothing to set, so no operation is performed.

Defining dictionaries using literal syntax

For information about how to define dictionaries using literal syntax, see Dictionary Literals.

Defining dictionaries using expression syntax

For information about how to define dictionaries using expression syntax, see Create a Dictionary<TKey, TItem>.

Dictionaries containing items with same data types vs different data types

For information about the different types of dictionaries, including those that can contain only the same type of item, and those that can contain different types of item, see Dictionaries.

6.3.5 - Email

Blocks related to working with Emails.

6.3.5.1 - Send Email

Blocks related to sending Emails.

6.3.5.1.1 - Send Email Using SMTP Server

Sends an email using the specified SMTP server.
Icon

Send Email Using SMTP Server

(Cortex.Blocks.Email.SendEmail.SendEmailUsingSmtpServerBlock)

Description

Connects to an SMTP server using the specified Basic Email Session Details, and sends an Email Message.

Close Session can be specified to choose whether the connection to the SMTP server is closed or is kept open for use on subsequent Send Email Using SMTP Server blocks.

Examples

Sending an email to a single recipient

This example will send an email from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be to set to true within the Basic Email Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email to multiple recipients

This example will send an email from sender@gmail.com to recipient1@outlook.com, recipient2@outlook.com and recipient3@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient1@outlook.com"}, {"Name": null, "Address": "recipient2@outlook.com"}, {"Name": null, "Address": "recipient3@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient1@outlook.com"), new EmailAddress("recipient2@outlook.com"), new EmailAddress("recipient3@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient1@outlook.com, recipient2@outlook.com and recipient3@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with a CC or BCC recipient

This example will send an email from sender@gmail.com to recipient@outlook.com with cc@outlook.com and bcc@outlook.com as the CC and BCC recipients for the email respectively. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List<EmailAddress>(){ new EmailAddress("cc@outlook.com") }, bcc: new List<EmailAddress>(){ new EmailAddress("bcc@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body". Both cc@outlook.com and bcc@outlook.com will also recieve copies of the email as they are listed as CC and BCC recipients, and then the session is closed.


Sending an email with multiple CC or BCC recipients

This example will send an email from sender@gmail.com to recipient@outlook.com with cc1@outlook.com and cc2@outlook.com as the CC recipients and bcc1@outlook.com and bcc2@outlook.com as the BCC recipients for the email. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [{"Name": null, "Address": "cc1@outlook.com"}, {"Name": null, "Address": "cc2@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc1@outlook.com"}, {"Name": null, "Address": "bcc2@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List<EmailAddress>(){ new EmailAddress("cc1@outlook.com"), new EmailAddress("cc2@outlook.com") }, bcc: new List<EmailAddress>(){ new EmailAddress("bcc1@outlook.com"), new EmailAddress("bcc2@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body". Both cc1@outlook.com and cc2@outlook.com will also recieve copies of the email as they are listed as CC recipients, and both bcc1@outlook.com and bcc2@outlook.com will recieve copies of the email as they are listed as BCC recipients. Finally, the session is closed.


Sending an email with a different priority

This example will send an email with Urgent priority from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As BodyFormat is null, the email will be sent with a Text body.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Urgent priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with an HTML body

This example will send an email with an HTML body from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Html", "Body": "<h1>Example email body</h1>", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Html, body: "<h1>Example email body</h1>", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority is null, the email will be sent with Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and an HTML body of "<h1>Example email body</h1>", and then the session is closed.


Sending an email with a single attachment

This example will send an email with a single attachment, attachment.txt, from sender@gmail.com to recipient@outlook.com. The attachment is located at C:\attachment.txt on the server executing the flow. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List<string>(){ @"C:\attachment.txt" })
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.

The Attachments are added to the email by providing file paths pointing to the files to be attached to the email.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority containing a text file attachment, attachment.txt, is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with multiple attachments

This example will send an email with mutiple attachments, attachment1.txt and attachment2.txt from sender@gmail.com to recipient@outlook.com. The attachments are located at the paths C:\attachment1.txt and C:\attachment2.txt on the server executing the flow. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Basic Email Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": ["C:\\attachment1.txt", "C:\\attachment2.txt"]}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List<string>(){ @"C:\attachment1.txt", @"C:\attachment2.txt" })
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.

The Attachments are added to the email by providing file paths pointing to the files to be attached to the email.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority containing two text file attachments, attachment1.txt and attachment2.txt, is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with UseSsl set to false

This example will send an email from sender@outlook.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp-mail.outlook.com on Port 587 which requires UseSsl to be set to false within the Basic Email Session Details.

For more information on when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Basic Email Session Details ($)BasicEmailSessionDetails with value {"ServerDetails": {"Host": "smtp-mail.outlook.com", "Port": 587, "UseSsl": false}, "Credentials": {"Domain": null, "Username": "sender@outlook.com", "Password": "encryptedPassword"}}

In this example ($)BasicEmailSessionDetails has been set up using the following Expression:

new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp-mail.outlook.com", 587, false), credentials: new UserCredentials("sender@outlook.com", "encryptedPassword"))
($)BasicEmailSessionDetails is a variable of type BasicEmailSessionDetails

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@outlook.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Properties

Email Message

The Email Message to send via the SMTP server specified in the Basic Email Session Details. This property contains all of the information in relation to the email to be sent, these are:

Note that if the properties Priority and BodyFormat are set to null when creating an EmailMessage using a constructor, the email will be sent with Normal priority and with a text body.

For more detailed information on each of the properties, see EmailMessage.

Data Type EmailMessage
Property Type Input
Is Advanced false
Default Editor Literal
Default Value EmailMessage with value shown below:
{
  "To": [
    {
      "Name": null,
      "Address": ""
    }
  ],
  "From": {
    "Name": "",
    "Address": ""
  },
  "Cc": [],
  "Bcc": [],
  "Priority": "EmailMessagePriority.Normal",
  "Subject": "",
  "BodyFormat": "EmailMessageBodyFormat.Text",
  "Body": "",
  "Attachments": []
}

Basic Email Session Details

The Basic Email Session Details object that includes all of the information required to open and maintain a session with an SMTP server, including:

If the Close Session property is set to false, then the session will be kept open and can be used in subsequent Send Email Using SMTP Server blocks which improves performance, see Opening Sessions for more information.

For more detailed information on each of the properties, see BasicEmailSessionDetails.

Data Type BasicEmailSessionDetails
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)BasicEmailSessionDetails with no value

Close Session

Close Session can be specified to choose whether the session is closed or is kept open for use on subsequent Send Email Using SMTP Server blocks, this defaults to false if left blank, please see Closing Sessions for more information.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when BodyFormat within the Email Message is not one of the specified EmailMessageBodyFormat values (e.g. (EmailMessageBodyFormat)10).
Thrown when Priority within the Email Message is not one of the specified EmailMessagePriority values (e.g. (EmailMessagePriority)10).
Thrown when a file path provided in the Attachments within the Email Message is empty (i.e. ""), contains only whitespace (i.e. " ") or contains the NUL character (i.e. \0).
ArgumentNullException Thrown when a file path provided in the Attachments within the Email Message is null.
EmailSessionException Thrown when an invalid Port is provided in the ServerDetails within the Basic Email Session Details. For more information, see Invalid Port.
Thrown when an invalid Host is provided in the ServerDetails within the Basic Email Session Details. For more information, see Invalid Host.
Thrown when a connection cannot be established; this typically occurs when UseSsl within Basic Email Session Details is set to false with a Port which requires it to be set to true. For more information, see SSL Required.
Thrown when a connection cannot be established; this typically occurs when UseSsl within Basic Email Session Details is set to true with a Port which requires it to be set to false. For more information, see SSL Unsupported.
Thrown when the TLS/SSL certificate has expired on the Host or is untrusted or invalid. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when a locally installed anti-virus software replaces the TLS/SSL certificate in order to scan web traffic. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when the CRL (Certificate Revocation List) server for the TLS/SSL certificate is down. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when the Username and Password in the UserCredentials within Basic Email Session Details is incorrect. For more information, see Invalid User Credentials.
FileNotFoundException Thrown when a non-existent file path is provided in Attachments within Email Message.
IOException Thrown when the desired socket is held by another process; re-running the flow typically solves this.
Thrown when a file path within Attachments within the Email Message contains leading spaces.
Thrown when a file path within Attachments within the Email Message contains invalid characters (i.e. ", *, ?, |, <, >, :, \, /).
PathTooLongException Thrown when a file path provided in the Attachments within the Email Message exceeds the system-defined maximum length (typically 32,767).
PropertyNullException Thrown when the Basic Email Session Details is null.
Thrown when the UserCredentials within Basic Email Session Details is null.
Thrown when the ServerDetails within Basic Email Session Details is null.
Thrown when the Host in ServerDetails within Basic Email Session Details is null.
Thrown when the Email Message is null.
Thrown when the To within Email Message is null.
Thrown when the From within Email Message is null.
Thrown when the Address in an EmailAddress within Email Message is null.
PropertyEmptyException Thrown when the Host in ServerDetails within Basic Email Session Details is empty (i.e. "").
Thrown when the To within Email Message is empty (i.e. []).
Thrown when the Address in an EmailAddress within Email Message is empty (i.e. "").
PropertyValueOutOfRangeException Thrown when the Port in the ServerDetails within Basic Email Session Details is below 1 or above 65535. For more information, see Property Is Invalid.
SmtpCommandException Thrown when the Address in an EmailAddress within Email Message is not of the correct format (RFC 5321).
Thrown when the combined size of all of the attachments in the list of Attachments within the Email Message is greater than the limit specified by the email service provider; for Outlook this is 20 MB and for Gmail this is 25 MB.
UnauthorizedAccessException Thrown when access is denied to a file provided in Attachments within Email Message.
Thrown when a file path within the Attachments property within Email Message points to a folder.

Remarks

How does Priority affect sending an email?

An email sent with Urgent or NonUrgent priority will have its priority displayed differently depending on the email client. For example, Outlook displays an email that has an Urgent priority with a red exclamation mark like so:

Important email

For more information on how the priority of an email will be displayed, see the help provided by the respective email client.

How does BodyFormat affect sending an email?

An email sent with an HTML body will have its body displayed as an HTML page instead of as plain text. How the email looks in the email client may differ depending on the email client in use. For example, if the Email Message has its BodyFormat set to HTML and the Body has a value of:

"<h1>Example header text</h1><p>Example paragraph text</p>"

Outlook will display the email body as follows:

HTML email

For more information on how the body of an email will be displayed, see the help provided by the respective email client.

Attachments

Attachments can be sent in an email by providing a list of file paths in the Attachments property of the Email Message. For more information concerning attaching files to an email, see the sections below.

Supported file path formats

Each file path in the Attachments within the Email Message can be an:

  • Absolute file path
  • Relative file path
  • UNC file path

where each file path must be accessible from the server executing the flow.

For more information about each of these supported file path formats, please see File & Folder Paths.

File paths need escaping

Each file path in the Attachments within the Email Message requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Attachments\\attachment.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Attachments\attachment.txt")

Null file path

If null is provided as a file path in the Attachments within the Email Message, an ArgumentNullException is thrown.

Empty file path

If an empty string is provided as a file path in the the Attachments within the Email Message, an ArgumentException is thrown.

File path does not exist

If a file path in the Attachments within the Email Message does not exist, a FileNotFoundException is thrown.

Invalid file path

If a file path in the Attachments within the Email Message is invalid (i.e. contains any of the following characters: “, *, ?, |, <, >, :, , /), an IOException will be thrown.

File path points to a folder

If a file path in the Attachments within the Email Message points to a folder, an UnauthorizedAccessException will be thrown.

File path contains leading spaces

If a file path in the Attachments within the Email Message contains leading spaces they are not removed and an IOException will be thrown; however, trailing spaces are removed.

File path contains only whitespace or the NUL character

If a file path in the Attachments within the Email Message contains only whitespace (i.e. " ") or the NUL character (i.e. \0), an ArgumentException will be thrown.

File path exceeds the system-defined maximum length

If a file path in the Attachments within the Email Message exceeds the system-defined maximum length (typically 32,767), a PathTooLongException will be thrown.

User does not have necessary permissions to attach the file

If the user the flow is executing as does not have permissions to access the file at the provided file path in the Attachments within the Email Message, an UnauthorizedAccessException will be thrown.

Attachment size limit

The combined size of all the Attachments within the Email Message must be less than the limit specified by the email service provider. If the combined size of all of the attachments is greater than the limit, an SmtpCommandException will be thrown.

For Outlook this is 20 MB and for Gmail this is 25 MB, for more information on the size limits for other email service providers, see the help provided by the respective email service provider.

Supported formats for ServerDetails.Host

The following formats are supported for Host in ServerDetails:

  • Fully Qualified Domain Name (e.g. "smtp.gmail.com")
  • Machine name (e.g. "mail-server1")
  • IP address (e.g. "127.0.0.1")
  • Localhost (e.g. "localhost")

Setting UseSsl

The ServerDetails within the Basic Email Session Details specifies which SMTP server to connect to. The value of the UseSsl property inside this object depends on the Host and Port being connected to. There are two types of SSL/TLS connections that can occur:

  • SSL/TLS is used as soon as a connection is established
  • SSL/TLS is used via the STARTTLS command if it is available

The above two points correspond to the UseSsl property being set to true and false respectively. As such, generally the following rules can be followed to determine whether UseSsl should be set to true or false:

  • If the Port being connected to is 465 then UseSsl should be set to true
  • If the Port being connected to is 25 or 587 then UseSsl should be set to false

Setting Credentials

The UserCredentials within the Basic Email Session Details specifies what user to connect as on the SMTP server. The value of the Username property may optionally be encrypted, however the Password must be encrypted otherwise an UnencryptedTextException will be thrown when the object is created. For more information on how to encrypt the password, see EncryptedText.

Note that the UserCredentials object also contains a Domain property which is ignored by this block.

Opening Sessions

The Send Email Using SMTP Server block automatically handles creating and opening sessions for the specified Basic Email Session Details using the following rules:

  • If a session does not exist, a new session will be created, opened and used when the block runs.
  • If a session already exists but is closed, the session will be opened and used when the block runs.
  • If a session already exists and is open, the session will be used when the block runs.

Basic Email Session Details will keep the session open across multiple Send Email Using SMTP Server blocks as long as Close Session is set to false. Keeping the session open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening sessions for each execution.

Note that for all SSL connections, the protocol to be used will be negotiated with the server depending on which protocols are available. Similarly, the SASL mechanism to be used will be negotiated with the mail server based on the available mechanisms.

For information on how to explicitly close a session, please see Closing Sessions.

Closing Sessions

Sessions can be explicitly closed by setting Close Session to true. This causes the session to be closed after the Email Message has been sent.

If Close Session is set to false the session will be closed when the Variable that Basic Email Session Details is set to goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see Variables.

For information on how to open a session, please see Opening Sessions.

Known Limitations

Currently unauthenticated SMTP servers are not supported.

This limitation may be removed in the future.

6.3.6 - Exceptions

Blocks related to handling and throwing Exceptions.

6.3.6.1 - Handle Block Exception(s)

Handle exceptions that occur during block execution.

6.3.6.1.1 - Handle Block Exception

Handles any exception thrown by the block it is connected to.
Icon

Handle Block Exception

(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionBlock)

Description

Handles any Exception thrown by the block it is connected to.

Examples

Handle and save the Exception

This example will handle any exception thrown by the block it is connected to; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any exception and save the exception to the ($)Exception variable for use later in the flow execution.


Handle and discard the Exception from being saved

This example will handle any exception thrown by the block it is connected to; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any exception, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Properties

Exception

The Exception that is handled.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

No exceptions are thrown by the block.

Remarks

Chaining Exception handling blocks

Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below:

Icon

Each block has an input port on its left-hand side and, with the exception of this block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block.

As this block handles any exception, it does not require the output port.

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more information about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.1.2 - Handle Block Exception Matching Message

Handles any exception thrown by the block it is connected to that matches a specified message.
Icon

Handle Block Exception Matching Message

(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingMessageBlock)

Description

Handles any Exception thrown by the block it is connected to that matches a specified Message.

Examples

Handle Exception containing Message and save the Exception

This example will handle any exception thrown by the block it is connected to that contains "'List' is null" in its Message property; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Message ($)Message, with value "'List' is null" ($)Message is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any exception containing "'List' is null" in its Message property and save the exception to the ($)Exception variable for use later in the flow execution.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s Message property would be "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing "'List' is null" in their Message, this exception would be handled and saved to the ($)Exception variable.


Handle Exception containing Message and discard the Exception

This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Message ($)Message, with value "'List' is null" ($)Message is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any exception containing "'List' is null" in its Message property, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s Message property would be "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing "'List' is null" in their Message, this exception would be handled, but because the ($)_ variable is used it will not be saved to the ($)Exception variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Exception does not contain Message

This example will not handle an exception thrown by the block it is connected to that does not contain "'List' is null" in its Message property; the exception will be passed to the next exception handling block.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Message ($)Message, with value "'List' is null" ($)Message is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that won’t be set

Result

The block will not handle any exception that does not contain "'List' is null" in its Message property; instead the exception will be passed to the next exception handling block.

E.g.

If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a CannotModifyReadOnlyListException when executed.

This exception’s Message property would be "'List' cannot be modified because it's read-only.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing "'List' is null" in their Message, this exception would not be handled.


Properties

Message

The Message the Exception’s Message property must contain for this block to handle the Exception.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Comparison Type

The Comparison Type specifying the rules used to determine whether Message is contained in the Exception’s Message property.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exception

The Exception if it is handled by the block.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Message

If Message is null or empty (i.e. ""), and the thrown exception’s Message property is also null or empty (i.e. ""), the exception will be handled and saved to the variable specified in the Exception property.

Chaining Exception handling blocks

Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below:

Icon

Each block has an input port on its left-hand side and, with the exception of the Handle Block Exception block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block.

As the Handle Block Exception block handles any exception, it does not require the output port.

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.1.3 - Handle Block Exception Matching Messages

Handles any exception thrown by the block it is connected to that matches any message in a given set of messages.
Icon

Handle Block Exception Matching Messages

(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingMessagesBlock)

Description

Handles any Exception thrown by the block it is connected to that matches any message in a given set of Messages.

Examples

Handle Exception containing any of the Messages and save the Exception

This example will handle any exception thrown by the block it is connected to that contains any of the messages in ["'List' is null", "'List' is empty"] in its Message property; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Messages ($)Messages, with value ["'List' is null", "'List' is empty"] ($)Messages is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any exception containing any of the messages in ["'List' is null", "'List' is empty"] in its Message property and save the exception to the ($)Exception variable for use later in the flow execution.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s Message property would be "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing any of ["'List' is null", "'List' is empty"] in their Message, this exception would be handled and saved to the ($)Exception variable.


Handle Exception containing any of the Messages and discard the Exception

This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Messages ($)Messages, with value ["'List' is null", "'List' is empty"] ($)Messages is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any exception containing any of the messages in ["'List' is null", "'List' is empty"] in its Message property, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s Message property would be "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing any of ["'List' is null", "'List' is empty"] in their Message, this exception would be handled, but because the ($)_ variable is used it will not be saved to the ($)Exception variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Exception does not contain any of the Messages

This example will not handle an exception thrown by the block it is connected to that does not contain any of ["'List' is null", "'List' is empty"] in its Message property; the exception will be passed to the next exception handling block.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Messages ($)Messages, with value ["'List' is null", "'List' is empty"] ($)Messages is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that won’t be set

Result

The block will not handle any exception that does not contain any of ["'List' is null", "'List' is empty"] in its Message property; instead the exception will be passed to the next exception handling block.

E.g.

If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a CannotModifyReadOnlyListException when executed.

This exception’s Message property would be "'List' cannot be modified because it's read-only.\r\nPlease click the HelpLink for more information on how to fix this."; therefore as we are checking for exceptions containing any of ["'List' is null", "'List' is empty"] in their Message, this exception would not be handled.


Properties

Messages

The Messages the Exception’s Message property must contain any of for this block to handle the Exception.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<string>() {}

Comparison Type

The Comparison Type specifying the rules used to determine whether any of the Messages are contained in the Exception’s Message property.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exception

The Exception if it is handled by the block.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
PropertyEmptyException Thrown when Messages contains no items.
PropertyNullException Thrown when Messages is null.

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Message in Messages

If any message in Messages is null or empty (i.e. ""), and the thrown exception’s Message property is also null or empty (i.e. ""), the exception will be handled and saved to the variable specified in the Exception property.

Chaining Exception handling blocks

Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below:

Icon

Each block has an input port on its left-hand side and, with the exception of the Handle Block Exception block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block.

As the Handle Block Exception block handles any exception, it does not require the output port.

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.1.4 - Handle Block Exception Matching Type Name

Handles any exception thrown by the block it is connected to that matches a specified type name.
Icon

Handle Block Exception Matching Type Name

(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingTypeNameBlock)

Description

Handles any Exception thrown by the block it is connected to that matches a specified Type Name.

Examples

Handle Exception matching Type Name and save the Exception

This example will handle any exception thrown by the block it is connected to that contains "PropertyNull" in its fully qualified TypeName; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of type names.

Properties

Property Value Notes
Type Name ($)TypeName, with value "PropertyNull" ($)TypeName is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any exception containing "PropertyNull" in its fully qualified TypeName and save the exception to the ($)Exception variable for use later in the flow execution.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Common.Property.PropertyNullException"; therefore as we are checking for exceptions containing "PropertyNull" in their TypeName, this exception would be handled and saved to the ($)Exception variable.


Handle Exception matching Type Name and discard the Exception

This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of type names.

Properties

Property Value Notes
Type Name ($)TypeName, with value "PropertyNull" ($)TypeName is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any exception containing "PropertyNull" in its fully qualified TypeName, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Common.Property.PropertyNullException"; therefore as we are checking for exceptions containing "PropertyNull" in their TypeName, this exception would be handled, but because the ($)_ variable is used it will not be saved to the ($)Exception variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Exception does not match Type Name

This example will not handle an exception thrown by the block it is connected to that does not contain "PropertyNull" in its fully qualified TypeName; the exception will be passed to the next exception handling block.

It performs a case-sensitive, culture-insensitive comparison of type names.

Properties

Property Value Notes
Type Name ($)TypeName, with value "PropertyNull" ($)TypeName is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that won’t be set

Result

The block will not handle any exception that does not contain "PropertyNull" in its fully qualified TypeName; instead the exception will be passed to the next exception handling block.

E.g.

If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a CannotModifyReadOnlyListException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Lists.CannotModifyReadOnlyListException"; therefore as we are checking for exceptions containing "PropertyNull" in their TypeName, this exception would not be handled.


Properties

Type Name

The Type Name the Exception’s fully qualified TypeName must contain for this block to handle the Exception.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to null)

Comparison Type

The Comparison Type specifying the rules used to determine whether Type Name is contained in the Exception’s fully qualified TypeName.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exception

The Exception if it is handled by the block.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
PropertyEmptyException Thrown when Type Name is empty (i.e. "").
PropertyNullException Thrown when Type Name is null.

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Chaining Exception handling blocks

Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below:

Icon

Each block has an input port on its left-hand side and, with the exception of the Handle Block Exception block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block.

As the Handle Block Exception block handles any exception, it does not require the output port.

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.1.5 - Handle Block Exception Matching Type Names

Handles any exception thrown by the block it is connected to that matches any type name in a given set of type names.
Icon

Handle Block Exception Matching Type Names

(Cortex.Blocks.Exceptions.HandleBlockException.HandleBlockExceptionMatchingTypeNamesBlock)

Description

Handles any Exception thrown by the block it is connected to that matches any type name in a given set of Type Names.

Examples

Handle Exception matching any of the Type Names and save the Exception

This example will handle any exception thrown by the block it is connected to that contains any of the type names in ["PropertyNull", "PropertyEmpty"] in its fully qualified TypeName; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Type Names ($)TypeNames, with value ["PropertyNull", "PropertyEmpty"] ($)TypeNames is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any exception containing any of the type names in ["PropertyNull", "PropertyEmpty"] in its fully qualified TypeName and save the exception to the ($)Exception variable for use later in the flow execution.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Common.Property.PropertyNullException"; therefore as we are checking for exceptions containing any of ["PropertyNull", "PropertyEmpty"] in their TypeName, this exception would be handled and saved to the ($)Exception variable.


Handle Exception containing any of the Type Names and discard the Exception

This example is the same as the example above, except it does not save the exception to a variable, as the flow execution does not need it to make decisions or take further action.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Type Names ($)TypeNames, with value ["PropertyNull", "PropertyEmpty"] ($)TypeNames is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any exception containing any of the type names in ["PropertyNull", "PropertyEmpty"] in its fully qualified TypeName, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

E.g.

If the List property of the Add Item At Beginning list block was set to null, it would throw a PropertyNullException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Common.Property.PropertyNullException"; therefore as we are checking for exceptions containing any of ["PropertyNull", "PropertyEmpty"] in their TypeName, this exception would be handled, but because the ($)_ variable is used it will not be saved to the ($)Exception variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Exception does not contain any of the Type Names

This example will not handle an exception thrown by the block it is connected to that does not contain any of ["PropertyNull", "PropertyEmpty"] in its fully qualified TypeName; the exception will be passed to the next exception handling block.

It performs a case-sensitive, culture-insensitive comparison of messages.

Properties

Property Value Notes
Type Names ($)TypeNames, with value ["PropertyNull", "PropertyEmpty"] ($)TypeNames is a variable of type IEnumerable<String>
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Exception ($)Exception, with no value ($)Exception is a variable that won’t be set

Result

The block will not handle any exception that does not contain any of ["PropertyNull", "PropertyEmpty"] in its fully qualified TypeName; instead the exception will be passed to the next exception handling block.

E.g.

If the List property of the Add Item At Beginning list block was set to a read-only List, it would throw a CannotModifyReadOnlyListException when executed.

This exception’s fully qualified TypeName is "Cortex.Exceptions.Lists.CannotModifyReadOnlyListException"; therefore as we are checking for exceptions containing any of ["PropertyNull", "PropertyEmpty"] in their TypeName, this exception would not be handled.


Properties

Type Names

The Type Names the Exception’s fully qualified TypeName must contain any of for this block to handle the Exception.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<string>() {}

Comparison Type

The Comparison Type specifying the rules used to determine whether any of the Type Names are contained in the Exception’s fully qualified TypeName.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exception

The Exception if it is handled by the block.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
PropertyContainsNullOrEmptyItemException Thrown when any Type Name in Type Names is null or empty (i.e. "").
PropertyEmptyException Thrown when Type Names contains no items.
PropertyNullException Thrown when Type Names is null.

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Chaining Exception handling blocks

Blocks that handle block exceptions can be chained together so different exceptions can be handled separately. The blocks are listed below:

Icon

Each block has an input port on its left-hand side and, with the exception of the Handle Block Exception block, also have an output port on their right-hand side; this is so they can pass any exception they do not handle to the next block.

As the Handle Block Exception block handles any exception, it does not require the output port.

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.2 - Handle Flow Exception(s)

Handle exceptions not handled by any Handle Block Exception or Handle Workspace Exception blocks.

6.3.6.2.1 - Handle Flow Exception

Handles any unhandled exception within the Flow.
Icon

Handle Flow Exception

(Cortex.Blocks.Exceptions.HandleFlowException.HandleFlowExceptionWorkspaceBlock)

Description

Handles any unhandled Exception within the Flow.

For more information, please see Unhandled Exceptions.

Examples

Handle and save the Exception

This example will handle any unhandled exception within the Flow; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any unhandled exception within the Flow and save the exception to the ($)Exception variable for use later in the flow execution.


Handle and discard the Exception from being saved

This example will handle any unhandled exception within the Flow; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any unhandled exception within the Flow, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Properties

Exception

The Exception that is handled.

Exception can be any Exception data type.

By default, this property is assigned the built-in ($)_ variable, so the exception will be discarded. If the flow execution does need the exception, a variable can be assigned to save it in.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

No exceptions are thrown by the block.

Remarks

Block Restrictions

The following restrictions apply to this block:

Unhandled Exceptions

If an exception thrown by a block is not handled by any connected Handle Block Exception blocks, it will be passed to the Handle Workspace Exception block on the same workspace.

If the workspace does not contain a Handle Workspace Exception block it will be rethrown by the Workspace block the workspace belongs to.

This process repeats until:

If an exception occurs within the workspace of the Handle Flow Exception block and is not handled, the flow will end with a status of Error.

Icon

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.3 - Handle Workspace Exception(s)

Handle exceptions not handled by any Handle Block Exception blocks.

6.3.6.3.1 - Handle Workspace Exception

Handles any unhandled exception within its workspace.
Icon

Handle Workspace Exception

(Cortex.Blocks.Exceptions.HandleWorkspaceException.HandleWorkspaceExceptionBlock)

Description

Handles any unhandled Exception within its workspace.

For more information, please see Unhandled Exceptions.

Examples

Handle and save the Exception

This example will handle any unhandled exception within the block’s workspace; saving the exception to a variable, so the flow execution can use it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)Exception, with no value ($)Exception is a variable that will be set to a dynamic value

Result

The block will handle any unhandled exception within the block’s workspace and save the exception to the ($)Exception variable for use later in the flow execution.


Handle and discard the Exception from being saved

This example will handle any unhandled exception within the block’s workspace; not saving the exception to a variable, as the flow execution does not need it to make decisions or take further action.

Properties

Property Value Notes
Exception ($)_, with no value ($)_ is a built-in variable that indicates the flow execution does not need to save the exception, so it can be discarded

Result

The block will handle any unhandled exception within the block’s workspace, but will not save the exception as the ($)_ variable indicates it is not needed and can be discarded.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.


Properties

Exception

The Exception that is handled.

Exception can be any Exception data type.

If the flow execution does not need the exception, it can be discarded by assigning the built-in ($)_ variable.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)_ to discard

Exceptions

No exceptions are thrown by the block.

Remarks

Block Restrictions

The following restrictions apply to this block:

  • A workspace cannot contain more than one Handle Workspace Exception block. If more than one is added, it will be reported as a message when trying to debug the flow.
  • The Handle Workspace Exception block will only handle the first unhandled exception within its workspace. This is to prevent infinite recursion within the flow. Subsequent unhandled exceptions are passed to the next relevant exception handling block. For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.
  • A flow’s Top-Level Workspace cannot contain a Handle Workspace Exception block. If one is added, it will be reported as a message when trying to debug the flow.

Unhandled Exceptions

If an exception thrown by a block is not handled by any connected Handle Block Exception blocks, it will be passed to the Handle Workspace Exception block on the same workspace.

If the workspace does not contain a Handle Workspace Exception block it will be rethrown by the Workspace block the workspace belongs to.

This process repeats until:

If an exception occurs within the workspace of the Handle Flow Exception block and is not handled, the flow will end with a status of Error.

Icon

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Why does the Exception property return a dynamic data type?

The decision for the Exception to return a dynamic data type rather than an Exception data type, was to avoid users having to cast the exception to its correct type to be able to use all of its properties.

As a result, any issues with using the Exception data type (i.e. trying to access a property it does not have) will not be reported as messages when trying to debug the flow; they will only be discovered when the flow execution reaches the part of the flow with the issue.

If it is desirable to have any issues reported as messages when trying to debug the flow, the user can cast the exception to its correct type.

Using the built-in ($)_ variable to discard the Exception from being saved

Sometimes when an exception occurs the flow execution wants to use the exception to make decisions or take further action. However, there are occasions when the exception is not needed, and being forced to create another variable to save the exception is extra work for no benefit. In these circumstances it is possible to use the built-in ($)_ variable to indicate the exception does not need to be saved.

For more infomation about using the built-in ($)_ variable, please see Discarding Output Properties.

6.3.6.4 - Rethrow Exception

Rethrow a previously thrown and handled exception.

6.3.6.4.1 - Rethrow Exception

Rethrows an Exception which has previously been thrown and handled.
Icon

Rethrow Exception

(Cortex.Blocks.Exceptions.RethrowException.RethrowExceptionBlock)

Description

Rethrows an Exception which has previously been thrown and handled.

Examples

Rethrowing an Exception

This example will rethrow the following handled Exception thrown by an Add Item At Beginning block:

Icon

Properties

Property Value Notes
Exception ($)Exception, with value of{"Exception Type": "PropertyNullException","Message": "'List' is null; it must be provided with a non-null value.\r\nPlease click the HelpLink for more information on how to fix this.","HelpLink": "https://v2022.docs.cortex-ia.com/docs/reference/exceptions/common/property/property-null-exception"} ($)Exception is a variable of type PropertyNullException

Result

Rethrowing ($)Exception results in the Exception being rethrown and shown in the Exceptions Viewer:

Icon


Properties

Exception

The Exception that is rethrown.

Exception can be any Exception data type.

Data Type Exception
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Exception with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Exception is null.

Remarks

Propagating Exceptions

Sometimes it is necessary to propagate exceptions thrown in a child flow to the flow that called it. Currently, using the Rethrow Exception block to rethrow the Exception from the Handle Flow Exception workspace is the only way to achieve this. This can be seen below:

Rethrow from a subflow

In future, additional ways to propagate exceptions between flows may be added.

6.3.6.5 - Throw Exception

Throw an exception.

6.3.6.5.1 - Throw New Flow Exception

Throws a new FlowException with the specified message, category, error code, details, inner exception and help link.
Icon

Throw New Flow Exception

(Cortex.Blocks.Exceptions.ThrowException.ThrowNewFlowExceptionBlock)

Description

Throws a new FlowException with the specified Message, Category, Error Code, Details, Inner Exception and Help Link.

All properties are optional, and if not supplied will be set to the following default values:

Property Default Value
Message "Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown."
Category null
Error Code null
Details null
InnerException null
HelpLink https://v2022.docs.cortex-ia.com/docs/reference/exceptions/flows/flow-exception

Examples

Throw new FlowException with full configuration

This example will throw a new FlowException with all properties configured.

Properties

Property Value Notes
Message ($)Message, with value "Custom Message" ($)Message is a variable of type String
Category ($)Category, with value "Custom Category" ($)Category is a variable of type String
Error Code ($)ErrorCode, with value 100 ($)ErrorCode is a variable of type Nullable<Int32>
Details ($)Details, with value {"DetailsKey1" : "DetailsValue1", "DetailsKey2" : "DetailsValue2"} ($)Details is a variable of type IDictionary<String, String>
InnerException ($)InnerException, with value ($)Exception containing another FlowException with default properties ($)InnerException is a variable of type FlowException
HelpLink ($)HelpLink, with value "http://customdomain.com/customurl" ($)HelpLink is a variable of type String

Result

Throwing a new FlowException with properties configured as above will result in the following exception:

Icon


Throw new FlowException with no configuration

This example will throw a new FlowException with no configuration.

Properties

No properties are configured for this example.

Result

Throwing a new FlowException without configuring any of the block’s properties will result in the following exception:

Icon


Properties

Message

A Message describing the exception that occurred.

If Message is not provided or is set to null, it will default to "Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown.".

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Category

A Category that can be used to categorise similar types of exception that has occurred (e.g. an AuthenticationError category may be set for exceptions relating to authentication issues). This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Error Code

An Error Code that can be used to uniquely identify the type of exception (e.g. There may be multiple exceptions with the same AuthenticationError category set, such as InvalidCredentials, TokenExpired. In this case each exception can be assigned its own unique Error Code; InvalidCredentials = 100 and TokenExpired = 101). This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting.

If Error Code is not provided, it will default to null.

Data Type Nullable<Int32>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Details

Details can be used to provide more detailed information about the exception. It can be any type of Object. This can then be used for future decision making in the flow, or to assist in troubleshooting and reporting.

Data Type dynamic
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Inner Exception

Inner Exception can be used to include another exception within the thrown exception (e.g. If the FlowException has been thrown as a result of handling another exception, then the handled exception can be included within the FlowException to add traceability).

Data Type Exception
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

A Help Link can be specified where further information can be found about the exception being thrown.

If Help Link is not provided or is set to null, it will default to a link to the FlowException page; please note this page will not provide any guidance on how to fix the solution specific exception.

Data Type String
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

No exceptions are thrown by the block.

Remarks

Null Message

If Message is not provided or is set to null, it will default to "Exception of type 'Cortex.Exceptions.Flows.FlowException' was thrown.".

If Help Link is not provided or is set to null, it will default to a link to the FlowException page, please note this page will not provide any guidance on how to fix the solution specific exception.

6.3.7 - Files & Folders

Blocks related to working with Files and Folders.

6.3.7.1 - Check File Exists

Check if a file exists.

6.3.7.1.1 - Check File Exists

Checks if a file exists at the specified file path.
Icon

Check File Exists

(Cortex.Blocks.FilesAndFolders.CheckFile.CheckFileExistsBlock)

Description

Checks if a File Exists at the specified File Path.

Examples

File exists at the specified File Path

This example will check if "C:\Windows\System32\cmd.exe" exists on the Windows server executing the flow.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Windows\System32\cmd.exe" ($)FilePath is a variable of type String
File Exists ($)FileExists, with no value ($)FileExists is a variable that will be set to a Boolean value

Result

"C:\Windows\System32\cmd.exe" is the command prompt application on Windows machines. Checking this on the Windows server executing the flow will result in the variable ($)FileExists being updated to the following:

true

File does not exist at the specified File Path

This example will check if "/etc/passwd" exists on the Windows server executing the flow.

Properties

Property Value Notes
File Path ($)FilePath, with value "/etc/passwd" ($)FilePath is a variable of type String
File Exists ($)FileExists, with no value ($)FileExists is a variable that will be set to a Boolean value

Result

"/etc/passwd" is a file that exists on Linux machines containing the list of system accounts. Checking this on the Windows server executing the flow will result in the variable ($)FileExists being updated to the following:

false

Properties

File Path

The File Path to check a file exists at.

The File Path is case-insensitive, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

File Exists

The result of the file exists check.

If the file exists at the specified File Path, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)FileExists with no value

Exceptions

No exceptions are thrown by the block.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Windows\\System32\\cmd.exe"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Windows\System32\cmd.exe")

Null File Path

If File Path is null the variable specified in the File Exists property will be set to false.

Empty File Path

If File Path is empty (i.e. "") the variable specified in the File Exists property will be set to false.

Invalid File Path

If File Path is invalid (i.e. contains any of the following characters: ", *, ?, |, <, >, :, \, /) the variable specified in the File Exists property will be set to false.

File Path points to a folder

If File Path points to a folder, the variable specified in the File Exists property will be set to false.

To check if a folder exists, use the Check Folder Exists block.

File Path contains leading spaces

If File Path contains leading spaces they are not removed; however, trailing spaces are removed.

Error occurs whilst checking if the file exists

If any error occurs whilst checking if a file exists at the specified File Path, the variable specified in the File Exists property will be set to false.

User does not have necessary permissions to check if the file exists

If the user the flow is executing as does not have permissions to check if a file exists at the specified File Path, the variable specified in the File Exists property will be set to false.

6.3.7.2 - Check Folder Exists

Check if a folder exists.

6.3.7.2.1 - Check Folder Exists

Checks if a folder exists at the specified folder path.
Icon

Check Folder Exists

(Cortex.Blocks.FilesAndFolders.CheckFolder.CheckFolderExistsBlock)

Description

Checks if a Folder Exists at the specified Folder Path.

Examples

Folder exists at the specified Folder Path

This example will check if "C:\Windows\System32" exists on the Windows server executing the flow.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Windows\System32" ($)FolderPath is a variable of type String
Folder Exists ($)FolderExists, with no value ($)FolderExists is a variable that will be set to a Boolean value

Result

"C:\Windows\System32" is the folder on Windows machines that contains files critical to the functioning of the operating system. Checking this on the Windows server executing the flow will result in the variable ($)FolderExists being updated to the following:

true

Folder does not exist at the specified Folder Path

This example will check if "/etc" exists on the Windows server executing the flow.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value "/etc" ($)FolderPath is a variable of type String
Folder Exists ($)FolderExists, with no value ($)FolderExists is a variable that will be set to a Boolean value

Result

"/etc" is the folder on Linux machines containing system configuration files. Checking this on the Windows server executing the flow will result in the variable ($)FolderExists being updated to the following:

false

Properties

Folder Path

The Folder Path to check a folder exists at.

The Folder Path is case-insensitive, any trailing spaces will be automatically removed, and can end with or without a trailing \ (e.g. @"C:\Windows\System32" or @"C:\Windows\System32\").

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Folder Exists

The result of the folder exists check.

If the folder exists at the specified Folder Path, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)FolderExists with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Windows\\System32"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Windows\System32")

Null Folder Path

If Folder Path is null the variable specified in the Folder Exists property will be set to false.

Empty Folder Path

If Folder Path is empty (i.e. "") the variable specified in the Folder Exists property will be set to false.

Invalid Folder Path

If Folder Path is invalid (i.e. contains any of the following characters: ", *, ?, |, <, >, :, \, /) the variable specified in the Folder Exists property will be set to false.

Folder Path points to a file

If Folder Path points to a file, the variable specified in the Folder Exists property will be set to false.

To check if a file exists, use the Check File Exists block.

Folder Path contains leading spaces

If Folder Path contains leading spaces they are not removed; however, trailing spaces are removed.

Error occurs whilst checking if the folder exists

If any error occurs whilst checking if a folder exists at the specified Folder Path, the variable specified in the Folder Exists property will be set to false.

User does not have necessary permissions to check if the folder exists

If the user the flow is executing as does not have permissions to check if a folder exists at the specified Folder Path, the variable specified in the Folder Exists property will be set to false.

6.3.7.3 - Copy File(s)

Copy a file or multiple files.

6.3.7.3.1 - Copy File

Copies a file at the specified file path to the given destination path.
Icon

Copy File

(Cortex.Blocks.FilesAndFolders.CopyFile.CopyFileBlock)

Description

Copies a file at the specified File Path to the given Destination Path, with an option to Overwrite the file if it already exists.

Examples

Copy a file to a folder keeping the same file name

This example will copy "C:\Source\OriginalFile.txt" to "C:\Destination", with the same file name of "OriginalFile.txt".

In this example assume "C:\Destination" does not already contain a file named "OriginalFile.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\OriginalFile.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Copying "C:\Source\OriginalFile.txt" to "C:\Destination" that does not already contain a file named "OriginalFile.txt" will:

  • Create a new file at "C:\Destination\OriginalFile.txt" with:
    • The content copied from "C:\Source\OriginalFile.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\OriginalFile.txt".
    • The File Attributes copied from "C:\Source\OriginalFile.txt".

Copy a file to a folder with a new name

This example will copy "C:\Source\OriginalFile.txt" to "C:\Destination", with a new file name of "NewFile.txt".

To rename the file when it is being copied, please note that the Destination Path must be a file path, rather than a folder path (e.g. "C:\Destination\NewFile.txt" rather than "C:\Destination").

In this example assume "C:\Destination" does not already contain a file named "NewFile.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\OriginalFile.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination\NewFile.txt" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Copying "C:\Source\OriginalFile.txt" to the path "C:\Destination\NewFile.txt" that does not already exist will:

  • Create a new file at "C:\Destination\NewFile.txt" with:
    • The content copied from "C:\Source\OriginalFile.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\OriginalFile.txt".
    • The File Attributes copied from "C:\Source\OriginalFile.txt".

Copy a file to a folder overwriting any file that already exists with the same name

This example will copy "C:\Source\FileAlreadyExists.txt" to "C:\Destination", with the same file name of "FileAlreadyExists.txt".

In this example assume "C:\Destination" already contains a file named "FileAlreadyExists.txt", so overwrite must be set to true to ensure the content of the existing file can be overwritten.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\FileAlreadyExists.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean

Result

Copying "C:\Source\FileAlreadyExists.txt" to "C:\Destination" and overwriting the existing file named "FileAlreadyExists.txt" will:

  • Overwrite the existing file at "C:\Destination\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\FileAlreadyExists.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists.txt".

Properties

File Path

The File Path to copy the file from.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Destination Path

The Destination Path to copy the file to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path can either point to a folder or a file:

  • If it points to a folder, the copied file will have the name specified in the File Path.
  • If it points to a file, the copied file will have the name specified in the Destination Path.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the file in the Destination Path if it already exists.

If the file exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The Destination Path (if it points to a file), or the Destination Path (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The File Path does not exist.
The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path or Destination Path is invalid (for example, it is on an unmapped drive).
The file in the specified Destination Path exists and overwrite is false.
The file in the specified Destination Path exists, is read-only and overwrite is true.
The file in the specified Destination Path exists, is hidden and overwrite is true, but the file in the specified File Path is not hidden.
The user the flow is executing as does not have the required permissions to copy the file (e.g. not having read access to the File Path or write access to the Destination Path).
An unexpected error occurs when copying the file.
PropertyEmptyException Thrown when File Path or Destination Path are empty (i.e. "").
PropertyNullException Thrown when File Path or Destination Path are null.

Remarks

File and Folder Paths

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path and Destination Path need escaping

File Path and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\OriginalFile.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\OriginalFile.txt") and Destination Path (e.g. @"C:\Destination").

File Attributes

When copying a file from the File Path to the new Destination Path, all of the file’s attributes will also be copied.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

6.3.7.3.2 - Copy Files

Copies files at the specified file paths to the given destination path.
Icon

Copy Files

(Cortex.Blocks.FilesAndFolders.CopyFile.CopyFilesBlock)

Description

Copies files at the specified File Paths to the given Destination Path, with an option to Overwrite the files if they already exist.

Examples

Copy files to a folder keeping the same file names

This example will copy ["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"] to "C:\Destination", with the same file names of "OriginalFile1.txt" and "OriginalFile2.txt".

In this example assume "C:\Destination" does not already contain a file named "OriginalFile1.txt" or a file named "OriginalFile2.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\OriginalFile1.txt", @"C:\Source\OriginalFile2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Copying ["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"] to "C:\Destination" that does not already contain files named "OriginalFile1.txt" and "OriginalFile2.txt" will:

  • Create a new file at "C:\Destination\OriginalFile1.txt" with:
    • The content copied from "C:\Source\OriginalFile1.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\OriginalFile1.txt".
    • The File Attributes copied from "C:\Source\OriginalFile1.txt".
  • Create a new file at "C:\Destination\OriginalFile2.txt" with:
    • The content copied from "C:\Source\OriginalFile2.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\OriginalFile2.txt".
    • The File Attributes copied from "C:\Source\OriginalFile2.txt".

Copy files to a folder overwriting any files that already exists with the same names

This example will copy ["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"] to "C:\Destination", with the same file names of "FileAlreadyExists1.txt" and "FileAlreadyExists2.txt".

In this example assume "C:\Destination" already contains a file named "FileAlreadyExists1.txt" and a file named "FileAlreadyExists2.txt", so overwrite must be set to true to ensure the content of the existing files can be overwritten.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\FileAlreadyExists1.txt", @"C:\Source\FileAlreadyExists2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean

Result

Copying ["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"] to "C:\Destination" and overwriting the existing files named "FileAlreadyExists1.txt" and "FileAlreadyExists2.txt" will:

  • Overwrite the existing file at "C:\Destination\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists1.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\FileAlreadyExists1.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists1.txt".
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists2.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\FileAlreadyExists2.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists2.txt".

Properties

File Paths

The File Paths to copy the files from.

Each file path in File Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePaths with no value

Destination Path

The Destination Path to copy the files to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The copied files will have the names specified in the File Paths.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the files in the Destination Path if they already exist.

If any file exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path does not point to a folder.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The Destination Path (if it points to a file), or the Destination Path (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException Any file path in File Paths is null or empty (i.e. ""). For more information, see Null or Empty File Paths
Any file path in File Paths is duplicated. For more information, see Duplicate File Paths
Any file path in File Paths does not exist.
Any file path in File Paths points to a folder.
Any file path in File Paths contains leading spaces.
Any file path in File Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
Any file path in File Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any file path in File Paths or Destination Path is invalid (for example, it is on an unmapped drive).
Any file path in File Paths exists in the specified Destination Path and overwrite is false.
Any file path in File Paths exists in the specified Destination Path with the same name, is read-only and overwrite is true.
Any file path in File Paths exists in the specified Destination Path with the same name, is hidden and overwrite is true, but the file in the specified File Paths is not hidden.
The user the flow is executing as does not have the required permissions to copy any file (e.g. not having read access to a file path in File Paths or write access to the Destination Path).
An unexpected error occurs when copying a file.
PropertyEmptyException Thrown when File Paths does not contain any items, or Destination Path is empty (i.e. "").
PropertyNullException Thrown when File Paths or Destination Path are null.

Remarks

File and Folder Paths

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Paths and Destination Path need escaping

Each file path in File Paths and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\OriginalFile.txt"), or
  • Prepending an @ character before the start of the file path (e.g. @"C:\Source\OriginalFile.txt") and Destination Path (e.g. @"C:\Destination").

File Attributes

When copying a file in the File Paths to the new Destination Path, all of the file’s attributes will also be copied.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Handling of Exceptions

If an exception occurs when trying to copy a file in the File Paths, it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.4 - Copy Folder(s)

Copy a folder or multiple folders.

6.3.7.4.1 - Copy Folder

Copies a folder at the specified folder path to the given destination path.
Icon

Copy Folder

(Cortex.Blocks.FilesAndFolders.CopyFolder.CopyFolderBlock)

Description

Copies a folder at the specified Folder Path to the given Destination Path, with an option to copy the folder and its content, or just its Content Only.

An option can also be specified to Overwrite anything being copied that already exists in the Destination Path.

Examples

Copy a folder and its content

This example will copy "C:\Source\Folder" and its content to "C:\Destination".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".
  • "C:\Destination" does not already contain a folder named "Folder", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Copying "C:\Source\Folder" and its content to "C:\Destination" that does not already contain a folder named "Folder" will:

  • Create a new folder at "C:\Destination\Folder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder".
  • Create a new folder at "C:\Destination\Folder\SubFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder\SubFolder".
  • Create a new file at "C:\Destination\Folder\File.txt" with:
    • The content copied from "C:\Source\Folder\File.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\File.txt".
    • The File attributes copied from "C:\Source\Folder\File.txt".

Copy a folder and its content, overwriting any content that already exists

This example will copy "C:\Source\Folder" and its content to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • An empty sub-folder named "SubFolderAlreadyExists".
    • A file named "File.txt".
    • A file named "FileAlreadyExists.txt".
  • "C:\Destination" already contains a folder named "Folder", which already contains:
    • A folder named "SubFolderAlreadyExists".
    • A file named "FileAlreadyExists.txt".

Therefore, overwrite must be set to true to ensure the existing "SubFolderAlreadyExists" and "FileAlreadyExists.txt" can be overwritten.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Copying "C:\Source\Folder" and its content to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\Folder", "C:\Destination\Folder\SubFolderAlreadyExists" and "C:\Destination\Folder\FileAlreadyExists.txt" already exist will:

  • Overwrite the existing folder at "C:\Destination\Folder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new empty folder at "C:\Destination\Folder\SubFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder\SubFolder".
  • Overwrite the existing folder at "C:\Destination\Folder\SubFolderAlreadyExists" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\Folder\File.txt" with:
    • The content copied from "C:\Source\Folder\File.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\File.txt".
    • The File attributes copied from "C:\Source\Folder\File.txt".
  • Overwrite the existing file at "C:\Destination\Folder\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The File attributes copied from "C:\Source\Folder\FileAlreadyExists.txt".

Copy a folder’s content only

This example will copy "C:\Source\Folder" content only to "C:\Destination".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".
  • "C:\Destination" does not already contain a folder named "SubFolder" or a file named "File.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Copying "C:\Source\Folder" content only to "C:\Destination" that does not already contain a folder named "SubFolder" or a file named "File.txt" will:

  • Create a new folder at "C:\Destination\SubFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder\SubFolder".
  • Create a new file at "C:\Destination\File.txt" with:
    • The content copied from "C:\Source\Folder\File.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\File.txt".
    • The File attributes copied from "C:\Source\Folder\File.txt".

Copy a folder’s content only, overwriting any content that already exists

This example will copy "C:\Source\Folder" content only to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • An empty sub-folder named "SubFolderAlreadyExists".
    • A file named "File.txt".
    • A file named "FileAlreadyExists.txt".
  • "C:\Destination" already contains:
    • A folder named "SubFolderAlreadyExists".
    • A file named "FileAlreadyExists.txt".

Therefore, overwrite must be set to true to ensure the existing "SubFolderAlreadyExists" and "FileAlreadyExists.txt" can be overwritten.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Copying "C:\Source\Folder" content only to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\SubFolderAlreadyExists" and "C:\Destination\FileAlreadyExists.txt" already exist will:

  • Create a new empty folder at "C:\Destination\SubFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder\SubFolder".
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\File.txt" with:
    • The content copied from "C:\Source\Folder\File.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\File.txt".
    • The File attributes copied from "C:\Source\Folder\File.txt".
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The File attributes copied from "C:\Source\Folder\FileAlreadyExists.txt".

Copy a folder and its content to the same location but with a different name

If it is required to copy a folder and its content into the same folder it is currently located in, but with a different name, then it is not possible to do with this block; the Duplicate Folder block must be used instead.


Copy a folder and its content to a different location but with a different name

If it is required to copy a folder and its content into a different folder than the one it is currently located in, but with a different name, then it is not possible to do with this block; the Rename Folder block must be used instead.


Properties

Folder Path

The Folder Path to copy the folder and/or its content from.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Destination Path

The Destination Path to copy the folder and/or its content to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The copied folders and files will have the same names as the folders and files copied.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the folder and/or contents being copied to in the Destination Path if they already exist.

If the folder and/or contents exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing folders and files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Content Only

Option to specify whether to copy the folder and its content or just the Content Only.

To copy the folder and its content, Content Only must be set to false; to copy just the content, Content Only must be set to true.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path points to a file.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Destination Path exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The Folder Path does not exist.
The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path or Destination Path is a win32 device path (i.e starts with a "\\.\").
The Folder Path or Destination Path is invalid (for example, it is on an unmapped drive).
The Folder Path and Destination Path point to the same folder and Content Only is true.
The Folder Path is a child folder in the Destination Path and Content Only is false.
Any file being copied already exists in the specified Destination Path and overwrite is false.
Any file being copied already exists in the specified Destination Path, is read-only and overwrite is true.
Any file being copied already exists in the specified Destination Path, is hidden and overwrite is true, but the file under the specified Folder Path is not hidden.
The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to the Folder Path or its content, or write access to the Destination Path).
The operation is cyclic (e.g. copying a folder into one of its sub-folders).
An unexpected error occurs when copying the folder or any of its content.
PropertyEmptyException Thrown when Folder Path or Destination Path are empty (i.e. "").
PropertyNullException Thrown when Folder Path or Destination Path are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path and Destination Path need escaping

Folder Path and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source") and Destination Path (e.g. @"C:\Destination").

Folder Attributes

When copying the folder at the specified Folder Path or any folder under it to the new Destination Path, if the copied folder already exists its attributes remain unchanged, otherwise they are copied.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

File Attributes

When copying a file under Folder Path to the new Destination Path, all of the file’s attributes are also copied.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Handling of Exceptions

If an exception occurs when trying to copy Folder Path, an OperationFailedException will be thrown.

6.3.7.4.2 - Copy Folders

Copies folders at the specified folder paths to the given destination path.
Icon

Copy Folders

(Cortex.Blocks.FilesAndFolders.CopyFolder.CopyFoldersBlock)

Description

Copies folders at the specified Folder Paths to the given Destination Path, with an option to copy the folders and their content, or just their Content Only.

An option can also be specified to Overwrite anything being copied that already exists in the Destination Path.

Examples

Copy folders and their content

This example will copy ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination".

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • A file named "File1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • A file named "File2.txt".
  • "C:\Destination" does not already contain a folder named "Folder1" or "Folder2", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Copying ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination" that does not already contain folders named "Folder1" and "Folder2" will:

  • Create a new folder at "C:\Destination\Folder1" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder1".
  • Create a new folder at "C:\Destination\Folder1\SubFolder1" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder1\SubFolder1".
  • Create a new file at "C:\Destination\Folder1\File1.txt" with:
    • The content copied from "C:\Source\Folder1\File1.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\File1.txt".
    • The File attributes copied from "C:\Source\Folder1\File1.txt".
  • Create a new folder at "C:\Destination\Folder2" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder2".
  • Create a new folder at "C:\Destination\Folder2\SubFolder2" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder2\SubFolder2".
  • Create a new file at "C:\Destination\Folder2\File2.txt" with:
    • The content copied from "C:\Source\Folder2\File2.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\File2.txt".
    • The File attributes copied from "C:\Source\Folder2\File2.txt".

Copy folders and their content, overwriting any content that already exists

This example will copy ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • An empty sub-folder named "SubFolderAlreadyExists1".
    • A file named "File1.txt".
    • A file named "FileAlreadyExists1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • An empty sub-folder named "SubFolderAlreadyExists2".
    • A file named "File2.txt".
    • A file named "FileAlreadyExists2.txt".
  • "C:\Destination" already contains:
    • A folder named "Folder1", which already contains:
      • A folder named "SubFolderAlreadyExists1".
      • A file named "FileAlreadyExists1.txt".
    • A folder named "Folder2", which already contains:
      • A folder named "SubFolderAlreadyExists2".
      • A file named "FileAlreadyExists2.txt".

Therefore, overwrite must be set to true to ensure the existing folders and files can be overwritten.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Copying ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\Folder1", "C:\Destination\Folder1\SubFolderAlreadyExists1", "C:\Destination\Folder1\FileAlreadyExists1.txt", "C:\Destination\Folder2", "C:\Destination\Folder2\SubFolderAlreadyExists2" and "C:\Destination\Folder2\FileAlreadyExists2.txt" already exist will:

  • Overwrite the existing folder at "C:\Destination\Folder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new empty folder at "C:\Destination\Folder1\SubFolder1" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder1\SubFolder1".
  • Overwrite the existing folder at "C:\Destination\Folder1\SubFolderAlreadyExists1" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\Folder1\File1.txt" with:
    • The content copied from "C:\Source\Folder1\File1.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\File1.txt".
    • The File attributes copied from "C:\Source\Folder1\File1.txt".
  • Overwrite the existing file at "C:\Destination\Folder1\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The File attributes copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
  • Overwrite the existing folder at "C:\Destination\Folder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new empty folder at "C:\Destination\Folder2\SubFolder2" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder2\SubFolder2".
  • Overwrite the existing folder at "C:\Destination\Folder2\SubFolderAlreadyExists2" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\Folder2\File2.txt" with:
    • The content copied from "C:\Source\Folder2\File2.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\File2.txt".
    • The File attributes copied from "C:\Source\Folder2\File2.txt".
  • Overwrite the existing file at "C:\Destination\Folder2\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The File attributes copied from "C:\Source\Folder2\FileAlreadyExists2.txt".

Copy the folders’ content only

This example will copy ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination".

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • A file named "File1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • A file named "File2.txt".
  • "C:\Destination" does not already contain a folder named "SubFolder1" or "SubFolder2" or a file named "File1.txt" or "File2.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Copying ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination" that does not already contain a folder named "SubFolder1" or "SubFolder2" or a file named "File1.txt" or "File2.txt" will:

  • Create a new folder at "C:\Destination\SubFolder1" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder1\SubFolder1".
  • Create a new file at "C:\Destination\File1.txt" with:
    • The content copied from "C:\Source\Folder1\File1.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\File1.txt".
    • The File attributes copied from "C:\Source\Folder1\File1.txt".
  • Create a new folder at "C:\Destination\SubFolder2" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder2\SubFolder2".
  • Create a new file at "C:\Destination\File2.txt" with:
    • The content copied from "C:\Source\Folder2\File2.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\File2.txt".
    • The File attributes copied from "C:\Source\Folder2\File2.txt".

Copy folders’ content only, overwriting any content that already exists

This example will copy ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • An empty sub-folder named "SubFolderAlreadyExists1".
    • A file named "File1.txt".
    • A file named "FileAlreadyExists1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • An empty sub-folder named "SubFolderAlreadyExists2".
    • A file named "File2.txt".
    • A file named "FileAlreadyExists2.txt".
  • "C:\Destination" already contains:
    • A folder named "SubFolderAlreadyExists1".
    • A folder named "SubFolderAlreadyExists2".
    • A file named "FileAlreadyExists1.txt".
    • A file named "FileAlreadyExists2.txt".

Therefore, overwrite must be set to true to ensure the existing folders and files can be overwritten.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Copying ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\SubFolderAlreadyExists1", "C:\Destination\SubFolderAlreadyExists2", "C:\Destination\FileAlreadyExists1.txt" and "C:\Destination\FileAlreadyExists2.txt" already exist will:

  • Create a new empty folder at "C:\Destination\SubFolder1" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder1\SubFolder1".
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists1" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\File1.txt" with:
    • The content copied from "C:\Source\Folder1\File1.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\File1.txt".
    • The File attributes copied from "C:\Source\Folder1\File1.txt".
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The File attributes copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
  • Create a new empty folder at "C:\Destination\SubFolder2" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder2\SubFolder2".
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists2" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Create a new file at "C:\Destination\File2.txt" with:
    • The content copied from "C:\Source\Folder2\File2.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\File2.txt".
    • The File attributes copied from "C:\Source\Folder2\File2.txt".
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Created left unchanged.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The File attributes copied from "C:\Source\Folder2\FileAlreadyExists2.txt".

Copy folders and their content to the same location but with a different name

If it is required to copy folders and their content into the same folder they are currently located in, but with a different name, then it is not possible to do with this block; the Duplicate Folder block must be used instead.


Copy folders and their content to a different location but with a different name

If it is required to copy folders and their content into a different folder than the one they are currently located in, but with a different name, then it is not possible to do with this block; the Rename Folder block must be used instead.


Properties

Folder Paths

The Folder Paths to copy the folders and/or their content from.

Each folder path in Folder Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPaths with no value

Destination Path

The Destination Path to copy the folders and/or their content to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The copied folders and files will have the same names as the folders and files copied.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the folders and/or contents being copied to in the Destination Path if they already exist.

If any of the folders and/or contents exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing folders and files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Content Only

Option to specify whether to copy the folders and their content or just the Content Only.

To copy the folders and their content, Content Only must be set to false; to copy just the content, Content Only must be set to true.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path points to a file.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Destination Path exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException Any folder path in Folder Paths is null or empty (i.e. ""). For more information, see Null or Empty Folder Paths
Any folder path in Folder Paths is duplicated. For more information, see Duplicate Folder Paths
Any folder path in Folder Paths does not exist.
Any folder path in Folder Paths points to a file.
Any folder path in Folder Paths contains leading spaces.
Any folder path in Folder Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
Any folder path in Folder Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any folder path in Folder Paths or Destination Path is a win32 device path (i.e starts with a "\\.\").
Any folder path in Folder Paths or Destination Path is invalid (for example, it is on an unmapped drive).
Any folder path in Folder Paths and Destination Path point to the same folder and Content Only is true.
Any folder path in Folder Paths is a child folder in the Destination Path and Content Only is false.
Any file being copied already exists in the specified Destination Path and overwrite is false.
Any file being copied already exists in the specified Destination Path, is read-only and overwrite is true.
Any file being copied already exists in the specified Destination Path, is hidden and overwrite is true, but the file under any of the specified Folder Paths is not hidden.
The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to any of the folders in Folder Paths or its content, or write access to the Destination Path).
The operation is cyclic (e.g. copying a folder into one of its sub-folders).
An unexpected error occurs when copying a folder or any of its content.
PropertyEmptyException Thrown when Folder Paths does not contain any items, or Destination Path are empty (i.e. "").
PropertyNullException Thrown when Folder Paths or Destination Path are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path and Destination Path need escaping

Each folder paths in Folder Paths and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the folder path (e.g. @"C:\Source") and Destination Path (e.g. @"C:\Destination").

Folder Attributes

When copying the folders at the specified Folder Paths or any folder under them to the new Destination Path, if the copied folder already exists its attributes remain unchanged, otherwise they are copied.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

File Attributes

When copying a file under any of the Folder Paths to the new Destination Path, all of the file’s attributes are also copied.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Conflicting Content

If two or more paths in the specified Folder Paths contain content (folders or files) with the same name, and Overwrite and Content Only are true:

  • The attributes of the folder/file in the Destination Path will be that of the first one copied.
  • For files, the content of the file in the Destination Path will be that of the last one copied.

Handling of Exceptions

If an exception occurs when trying to copy a folder in Folder Paths, it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.4.3 - Duplicate Folder

Copies a folder at the specified folder path to the same location but with a new name.
Icon

Duplicate Folder

(Cortex.Blocks.FilesAndFolders.CopyFolder.DuplicateFolderBlock)

Description

Copies a folder at the specified Folder Path to the same location but with a New Name.

Examples

Duplicate a folder

This example will make a copy of "C:\Source\Folder" at "C:\Source\CopyOfFolder".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
New Name ($)NewName, with value "CopyOfFolder" ($)NewName is a variable of type String

Result

Making a copy of "C:\Source\Folder" with a new name of "CopyOfFolder" will:

  • Create a new folder at "C:\Source\CopyOfFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder".
  • Create a new folder at "C:\Source\CopyOfFolder\SubFolder" with:
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified set to the time the copy occurred.
    • The Folder attributes copied from "C:\Source\Folder\SubFolder".
  • Create a new file at "C:\Source\CopyOfFolder\File.txt" with:
    • The content copied from "C:\Source\Folder\File.txt".
    • The Date Created set to the time the copy occurred.
    • The Date Accessed set to the time the copy occurred.
    • The Date Modified copied from "C:\Source\Folder\File.txt".
    • The File attributes copied from "C:\Source\Folder\File.txt".

Other Copy Operations

If any other folder copying operation is required, the Copy Folder or Copy Folders blocks must be used instead.


Properties

Folder Path

The Folder Path to copy the folder and its content from.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

New Name

The New Name to use for the copy of the folder.

The New Name is case-insensitive and any trailing spaces will be automatically removed.

The New Name must be a valid folder name, otherwise an InvalidFolderNameException will be thrown.

All child folders and files copied will have the same names as the folders and files copied.

For information about valid folder names, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidFolderNameException A folder or file with the New Name already exists.
The New Name contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /).
The New Name exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The Folder Path does not exist.
The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path is a win32 device path (i.e starts with a "\\.\").
The Folder Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to copy the folder or any of its content (e.g. not having read access to the Folder Path or its content, or write access to the parent of Folder Path.
An unexpected error occurs when copying the folder or any of its content.
PropertyEmptyException Thrown when Folder Path or New Name are empty (i.e. "").
PropertyNullException Thrown when Folder Path or New Name are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

Folder Attributes

When copying the folder at or any folder under the specified Folder Path all of the folder’s attributes are also copied.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

File Attributes

When copying a file under Folder Path all of the file’s attributes are also copied.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Handling of Exceptions

If an exception occurs when trying to copy Folder Path, an OperationFailedException will be thrown.

6.3.7.5 - Create Folder(s)

Create a folder or multiple folders.

6.3.7.5.1 - Create Folder

Creates a folder at the specified folder path.
Icon

Create Folder

(Cortex.Blocks.FilesAndFolders.CreateFolder.CreateFolderBlock)

Description

Creates a folder at the specified Folder Path.

Examples

Create a folder

This example will create "C:\Source\NewFolder".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\NewFolder" ($)FolderPath is a variable of type String

Result

Creating "C:\Source\NewFolder" results in the folder "NewFolder" being created in the folder "C:\Source".


Properties

Folder Path

The Folder Path to create the folder at.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

Any folders that do not exist in the Folder Path will be created.

If the Folder Path already exists, a new folder is not created, and no exception is thrown.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to create the folder at the Folder Path.
An unexpected error occurs when creating the folder at the Folder Path or any of its content.
PropertyEmptyException Thrown when Folder Path is empty (i.e. "").
PropertyNullException Thrown when Folder Path is null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

Folder Path already exists

If the Folder Path already exists nothing is created, and no exception is thrown.

6.3.7.5.2 - Create Folders

Create folders at the specified folder paths.
Icon

Create Folders

(Cortex.Blocks.FilesAndFolders.CreateFolder.CreateFoldersBlock)

Description

Creates folders at the specified Folder Paths.

Examples

Create folders

This example will create ["C:\Source\NewFolder1", "C:\Source\NewFolder2"].

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\NewFolder1", @"C:\Source\NewFolder2"] ($)FolderPaths is a variable of type IEnumerable<String>

Result

Creating ["C:\Source\NewFolder1", "C:\Source\NewFolder2"] results in the folders "NewFolder1" and "NewFolder2" being create in the folder "C:\Source".


Properties

Folder Paths

The Folder Paths to create the folders at.

Each folder path in Folder Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

Any folders that do not exist in any of the Folder Paths will be created.

If a folder in Folder Paths already exists, a new folder is not created, and no exception is thrown.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPaths with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException Any folder path in Folder Paths is null or empty (i.e. ""). For more information, see Null or Empty Folder Paths.
Any folder path in Folder Paths is duplicated. For more information, see Duplicate Folder Paths.
Any folder path in Folder Paths points to a file.
Any folder path in Folder Paths contains leading spaces.
Any folder path in Folder Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
Any folder path in Folder Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any folder path in Folder Paths is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to create a folder in the Folder Paths.
An unexpected error occurs when creating a folder in the Folder Paths or any of its content.
PropertyEmptyException Thrown when Folder Paths does not contain any items.
PropertyNullException Thrown when Folder Paths is null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Paths need escaping

Each folder path in Folder Paths requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the folder path (e.g. @"C:\Source").

Folder Path already exists

If a folder path in Folder Paths already exists nothing is created, and no exception is thrown.

Handling of Exceptions

If an exception occurs when trying to create a folder in Folder Paths, it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.6 - Delete File(s)

Delete a file or multiple files.

6.3.7.6.1 - Delete File

Deletes a file at the specified file path.
Icon

Delete File

(Cortex.Blocks.FilesAndFolders.DeleteFile.DeleteFileBlock)

Description

Deletes a file at the specified File Path.

Examples

Delete a file

This example will delete "C:\Source\File.txt".

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String

Result

Deleting "C:\Source\File.txt" results in the file "File.txt" being deleted from the folder "C:\Source".


Properties

File Path

The File Path to delete the file from.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

If the File Path exists it is permanently deleted; it does not go into a recycle bin.

If the File Path does not exist no exception is thrown.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The file at the specified File Path is read-only.
The file at the specified File Path is in use by another application.
The user the flow is executing as does not have the required permissions to delete the file.
An unexpected error occurs when deleting the file.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

File Path does not exist

If the File Path does not exist nothing is deleted, and no exception is thrown.

6.3.7.6.2 - Delete Files

Deletes files at the specified file paths.
Icon

Delete Files

(Cortex.Blocks.FilesAndFolders.DeleteFile.DeleteFilesBlock)

Description

Deletes files at the specified File Paths.

Examples

Delete files

This example will delete files ["C:\Source\File1.txt", "C:\Source\File2.txt"].

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\File1.txt", @"C:\Source\File2.txt"] ($)FilePaths is a variable of type IEnumerable<String>

Result

Deleting ["C:\Source\File1.txt", "C:\Source\File2.txt"] results in files "File1.txt" and "File2.txt" being deleted from the folder "C:\Source".


Properties

File Paths

The File Paths to delete the files from.

Each file path in File Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

If a file path in File Paths exists it is permanently deleted; it does not go into a recycle bin.

If a file path in File Paths does not exist no exception is recorded for that file path.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePaths with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException Any file path in File Paths is null or empty (i.e. ""). For more information, see Null or Empty File Paths.
Any file path in File Paths is duplicated. For more information, see Duplicate File Paths.
Any file path in File Paths points to a folder.
Any file path in File Paths contains leading spaces.
Any file path in File Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
Any file path in File Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any file path in File Paths is invalid (for example, it is on an unmapped drive).
Any file path in File Paths is read-only.
Any file path in File Paths is in use by another application.
The user the flow is executing as does not have the required permissions to delete a file in File Paths.
An unexpected error occurs when deleting a file in File Paths.
PropertyEmptyException Thrown when File Paths does not contain any items.
PropertyNullException Thrown when File Paths is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Paths need escaping

Each file path in File Paths requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the file path (e.g. @"C:\Source\File.txt").

File Path does not exist

If a file path in File Paths does not exist no exception is recorded for that file path.

Handling of Exceptions

If an exception occurs when trying to delete a file in the File Paths, it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.7 - Delete Folder(s)

Delete a folder or multiple folders.

6.3.7.7.1 - Delete Folder

Deletes a folder at the specified folder path.
Icon

Delete Folder

(Cortex.Blocks.FilesAndFolders.DeleteFolder.DeleteFolderBlock)

Description

Deletes a folder at the specified Folder Path.

A Recursive option must be set to true to be able to delete a folder that contains files and/or other folders. This is to prevent unintentional and destructive deletion of files and folders.

Examples

Delete an empty folder

This example will delete "C:\Source\EmptyFolder".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\EmptyFolder" ($)FolderPath is a variable of type String
Recursive ($)Recursive, with value false ($)Recursive is a variable of type Boolean

Result

Deleting "C:\Source\EmptyFolder" results in the folder "EmptyFolder" being deleted from the folder "C:\Source".


Delete a folder and its content

This example will delete "C:\Source\Folder" and its content.

In this example assume:

  • "C:\Source\Folder" contains:
    • A file named "FileInFolder.txt".
    • An empty sub-folder named "EmptySubFolder".
    • An sub-folder named "SubFolder" that contains.
      • A file named "FileInSubFolder.txt".

Therefore, recursive must be set to true to ensure child folders and files can be deleted.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Recursive ($)Recursive, with value true ($)Recursive is a variable of type Boolean

Result

Deleting "C:\Source\Folder" and its content results in:

  • File "FileInSubFolder.txt" being deleted from the folder "C:\Source\Folder\SubFolder".
  • Folder "SubFolder" being deleted from the folder "C:\Source\Folder".
  • Folder "EmptySubFolder" being deleted from the folder "C:\Source\Folder".
  • File "FileInFolder.txt" being deleted from the folder "C:\Source\Folder".
  • Folder "Folder" being deleted from the folder "C:\Source".

Properties

Folder Path

The Folder Path to delete the folder from.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Recursive

Recursive option that must be set to true to be able to delete a folder that contains files and/or other folders.

If Recursive is set to false, only an empty folder will be able to be deleted; for a non-empty folder an OperationFailedException will be thrown.

By default, this is set to false to prevent unintentional and destructive deletion of files and folders.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The folder at the Folder Path is not empty and recursive is false.
The folder at the Folder Path or any sub-folders are read-only or contain read-only files and/or folders.
The user the flow is executing as does not have the required permissions to delete the folder at the Folder Path or any of its content.
An unexpected error occurs when deleting the folder at the Folder Path or any of its content.
PropertyEmptyException Thrown when Folder Path is empty (i.e. "").
PropertyNullException Thrown when Folder Path is null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

Folder Path does not exist

If the Folder Path does not exist nothing is deleted, and no exception is thrown.

Handling of Exceptions

If an exception occurs when trying to delete Folder Path, an OperationFailedException will be thrown.

6.3.7.7.2 - Delete Folders

Deletes folders at the specified folder paths.
Icon

Delete Folders

(Cortex.Blocks.FilesAndFolders.DeleteFolder.DeleteFoldersBlock)

Description

Deletes folders at the specified Folder Paths.

A Recursive option must be set to true to be able to delete folders that contain files and/or other folders. This is to prevent unintentional and destructive deletion of files and folders.

Examples

Delete empty folders

This example will delete ["C:\Source\EmptyFolder1", "C:\Source\EmptyFolder2"].

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\EmptyFolder1", @"C:\Source\EmptyFolder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Recursive ($)Recursive, with value false ($)Recursive is a variable of type Boolean

Result

Deleting ["C:\Source\EmptyFolder1", "C:\Source\EmptyFolder2"] results in the folders "EmptyFolder1" and "EmptyFolder2" being deleted from the folder "C:\Source".


Delete folders and their content

This example will delete ["C:\Source\Folder1", "C:\Source\Folder2"] and their content.

In this example assume:

  • "C:\Source\Folder1" contains:
    • A file named "FileInFolder1.txt".
    • An empty sub-folder named "EmptySubFolder1".
    • An sub-folder named "SubFolder1" that contains.
      • A file named "FileInSubFolder1.txt".
  • "C:\Source\Folder2" contains:
    • A file named "FileInFolder2.txt".
    • An empty sub-folder named "EmptySubFolder2".
    • An sub-folder named "SubFolder2" that contains.
      • A file named "FileInSubFolder2.txt".

Therefore, recursive must be set to true to ensure child folders and files can be deleted.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Recursive ($)Recursive, with value true ($)Recursive is a variable of type Boolean

Result

Deleting [@"C:\Source\Folder1", @"C:\Source\Folder2"] and their content results in:

  • File "FileInSubFolder1.txt" being deleted from the folder "C:\Source\Folder1\SubFolder1".
  • File "FileInSubFolder2.txt" being deleted from the folder "C:\Source\Folder2\SubFolder2".
  • Folder "SubFolder1" being deleted from the folder "C:\Source\Folder1".
  • Folder "SubFolder2" being deleted from the folder "C:\Source\Folder2".
  • Folder "EmptySubFolder1" being deleted from the folder "C:\Source\Folder1".
  • Folder "EmptySubFolder2" being deleted from the folder "C:\Source\Folder2".
  • File "FileInFolder1.txt" being deleted from the folder "C:\Source\Folder1".
  • File "FileInFolder2.txt" being deleted from the folder "C:\Source\Folder2".
  • Folder "Folder1" being deleted from the folder "C:\Source".
  • Folder "Folder2" being deleted from the folder "C:\Source".

Properties

Folder Paths

The Folder Paths to delete the folders from.

Each folder path in Folder Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPaths with no value

Recursive

Recursive option that must be set to true to be able to delete folders that contain files and/or other folders.

If Recursive is set to false, only empty folders will be able to be deleted; for non-empty folders an OperationFailedException will be thrown.

By default, this is set to false to prevent unintentional and destructive deletion of files and folders.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException Any folder path in Folder Paths is null or empty (i.e. ""). For more information, see Null or Empty Folder Paths.
Any folder path in Folder Paths is duplicated. For more information, see Duplicate Folder Paths.
Any folder path in Folder Paths points to a file.
Any folder path in Folder Paths contains leading spaces.
Any folder path in Folder Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
Any folder path in Folder Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any folder path in Folder Paths is not empty and recursive is false.
Any folder path in Folder Paths or any of their sub-folders are read-only or contain read-only files and/or folders.
The user the flow is executing as does not have the required permissions to delete a folder in the Folder Paths or any of its content.
An unexpected error occurs when deleting a folder in the Folder Paths or any of its content.
PropertyEmptyException Thrown when Folder Paths does not contain any items.
PropertyNullException Thrown when Folder Paths is null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Paths need escaping

Each folder path in Folder Paths requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the folder path (e.g. @"C:\Source").

Folder Path does not exist

If a folder path in Folder Paths does not exist no exception is recorded for that folder path.

Handling of Exceptions

If an exception occurs when trying to delete a folder in Folder Paths, it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.8 - Get File Information

Get information about a file (i.e. file attributes, created, accessed and modified dates etc.).

6.3.7.8.1 - Get File Information

Gets information about a file (e.g. file attributes, created, accessed, modified dates etc.) at the specified file path.
Icon

Get File Information

(Cortex.Blocks.FilesAndFolders.GetFileInformation.GetFileInformationBlock)

Description

Gets File Information about a file (e.g. file attributes, created, accessed, modified dates etc.) at the specified File Path.

Examples

Get file information

This example will get information about "C:\Source\File.txt".

In this example assume "C:\Source\File.txt":

  • Is on a server where local time and UTC time are the same (e.g. in UK).
  • Was created at 10.00am on the 1st January 2021.
  • Was last modified at 10.00am on the 1st January 2021.
  • Was last accessed at 1.00pm on the 10th January 2021.
  • Is 100 bytes in size.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
File Information ($)FileInformation, with no value ($)FilePath is a variable that will be set to a FileInformation value

Result

Getting file information for "C:\Source\File.txt" results in the variable ($)FileInformation being updated to the following:

{
    "Extension": ".exe",
    "Path": "C:\\Source\\File.txt",
    "Name": "File.txt",
    "ParentRoot": "C:\\",
    "ParentPath": "C:\\Source",
    "SizeInBytes": 100,
    "IsArchive": false,
    "IsCompressed": false,
    "IsEncrypted": false,
    "IsHidden": false,
    "IsNormal": false,
    "IsTemporary": false,
    "IsReadOnly": false,
    "IsSystem": false,
    "CreationTimeLocal": "2021-01-01T10:00:00+00:00",
    "CreationTimeUtc": "2021-01-01T10:00:00Z",
    "LastAccessTimeLocal": "2021-01-10T13:00:00+00:00",
    "LastAccessTimeUtc": "2021-01-10T13:00:00Z",
    "LastWriteTimeLocal": "2021-01-01T10:00:00+00:00",
    "LastWriteTimeUtc": "2021-01-01T10:00:00Z"
}

Properties

File Path

The File Path to get the File Information of.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

File Information

The File Information retrieved from the file at the specified File Path.

File Information includes file attributes, create, access and write dates and path details.

For more information see the example above, or the FileInformation data type.

Data Type FileInformation
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)FileInformation with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder or file names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to get information about the file at the File Path.
An unexpected error occurs when getting information for the file at the File Path.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

6.3.7.9 - Get Folder Content

Get the paths of files or folders in another folder.

6.3.7.9.1 - Get Folder Content

Gets the paths of files or folders under the specified folder path.
Icon

Get Folder Content

(Cortex.Blocks.FilesAndFolders.GetFolderContent.GetFolderContentBlock)

Description

Gets the Paths of files or folders under the specified Folder Path whose name matches the given Search Pattern.

The returned Paths can then be used in other file and folder blocks that require paths.

Additional options can be specified:

  • Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search.
  • Content Options can be specified to choose whether to search for files or folders.
  • A Recursive option can specified to choose whether to search only in the specified Folder Path, or include all subfolders.
  • A Comparison Type option can specified to choose how it is determined whether the file or folder name matches the Search Pattern (e.g. whether the search is case-sensitive or case-insensitive).

Examples

Get paths of files in a folder whose names contain a given text

This example will get the paths of all files in "C:\Source\Folder" that contain "file" in their name.

It will perform a case-insensitive search, and will not get any paths of folders or any paths of files that reside in subfolders of "C:\Source\Folder".

In this example assume "C:\Source\Folder" contains:

  • A file named "FileInFolder1.txt".
  • A file named "FileInFolder2.txt".
  • A folder named "SubFolder" which contains:
    • A file named "FileInSubFolder1.txt".
    • A file named "FileInSubFolder2.txt".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Search Pattern ($)SearchPattern, with value "file" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Content Options ($)ContentOptions, with value ContentOptions.Files ($)ContentOptions is a variable of type ContentOptions
Recursive ($)Recursive, with value false ($)Recursive is a variable of type Boolean
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Paths ($)Paths, with no value ($)Paths is a variable that will be set to an IList<String> value

Result

Getting all file paths that contain "file" (case-insensitive) in "C:\Source\Folder" excluding any of its subfolders, results in the variable ($)Paths being updated to the following:

[
    "C:\\Source\\Folder\\FileInFolder1.txt",
    "C:\\Source\\Folder\\FileInFolder2.txt"
]

Get paths of files in a folder (and its subfolders) whose names contain a given text

This example will get the paths of all files in "C:\Source\Folder" or any of its subfolders, that contain "File" in their name.

It will perform a case-sensitive search and will not get any paths of folders.

In this example assume "C:\Source\Folder" contains:

  • A file named "FileInFolder1.txt".
  • A file named "FileInFolder2.txt".
  • A folder named "SubFolder" which contains:
    • A file named "FileInSubFolder1.txt".
    • A file named "FileInSubFolder2.txt".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Search Pattern ($)SearchPattern, with value "File" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Content Options ($)ContentOptions, with value ContentOptions.Files ($)ContentOptions is a variable of type ContentOptions
Recursive ($)Recursive, with value true ($)Recursive is a variable of type Boolean
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Paths ($)Paths, with no value ($)Paths is a variable that will be set to an IList<String> value

Result

Getting all file paths that contain "File" (case-sensitive) in "C:\Source\Folder" or any of its subfolders, results in the variable ($)Paths being updated to the following:

[
    "C:\\Source\\Folder\\FileInFolder1.txt",
    "C:\\Source\\Folder\\FileInFolder2.txt",
    "C:\\Source\\Folder\\SubFolder\\FileInSubFolder1.txt",
    "C:\\Source\\Folder\\SubFolder\\FileInSubFolder2.txt"
]

Get paths of folders in a folder whose names match a given pattern

This example will get the paths of all folders that are in "C:\Source\Folder", and match the pattern "*" in their name.

It will perform a case-insensitive search, will not get any paths of files, and will match any folder in "C:\Source\Folder". It will not match any child folders of folders in "C:\Source\Folder".

In this example assume "C:\Source\Folder" contains:

  • A file named "FileInFolder1.txt".
  • A file named "FileInFolder2.txt".
  • A folder named "SubFolder" which contains:
    • A file named "FileInSubFolder1.txt".
    • A file named "FileInSubFolder2.txt".
    • An empty folder named "NestedSubFolder".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Search Pattern ($)SearchPattern, with value "*" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Content Options ($)ContentOptions, with value ContentOptions.Folders ($)ContentOptions is a variable of type ContentOptions
Recursive ($)Recursive, with value false ($)Recursive is a variable of type Boolean
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Paths ($)Paths, with no value ($)Paths is a variable that will be set to an IList<String> value

Result

Getting all folder paths that match the pattern "*" (case-insensitive) in "C:\Source\Folder" excluding any of its subfolders, results in the variable ($)Paths being updated to the following:

[
    "C:\\Source\\Folder\\SubFolder"
]

Get paths of folders in a folder (and its subfolders) whose names match a given regex

This example will get the paths of all folders that are in "C:\Source\Folder" or any of its subfolders, and match the regex "Folder$" in their name.

It will perform a case-sensitive search, will not get any paths of files, and will match folders whose name ends with "Folder".

In this example assume "C:\Source\Folder" contains:

  • A file named "FileInFolder1.txt".
  • A file named "FileInFolder2.txt".
  • A folder named "SubFolder" which contains:
    • A file named "FileInSubFolder1.txt".
    • A file named "FileInSubFolder2.txt".
    • An empty folder named "NestedSubFolder".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Search Pattern ($)SearchPattern, with value "Folder$" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Content Options ($)ContentOptions, with value ContentOptions.Folders ($)ContentOptions is a variable of type ContentOptions
Recursive ($)Recursive, with value true ($)Recursive is a variable of type Boolean
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Paths ($)Paths, with no value ($)Paths is a variable that will be set to an IList<String> value

Result

Getting all folder paths that match the regex "Folder$" (case-sensitive) in "C:\Source\Folder" or any of its subfolders, results in the variable ($)Paths being updated to the following:

[
    "C:\\Source\\Folder\\SubFolder",
    "C:\\Source\\Folder\\SubFolder\\NestedSubFolder"
]

Properties

Folder Path

The Folder Path to get the Paths of files or folders whose name matches the given Search Pattern.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Search Pattern

The Search Pattern file or folder names must match to be included in the returned Paths.

Only file or folder names are matched, not the whole path.

A Search Pattern of null or empty (i.e. "") means match any name; all additional block options such as Content Options etc. still take effect.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Search Options

Search Options can be specified to choose whether Search Pattern should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the file or folder name contains the text specified in Search Pattern it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Content Options

Content Options can be specified to choose whether Search Pattern should be match file or folder names.

  • ContentOptions.Files restricts the search to match only files.
  • ContentOptions.Folders restricts the search to match only folders.
Data Type ContentOptions
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Files

Recursive

Recursive option can specified to choose whether to search only in the specified Folder Path, or include all subfolders.

To search only in the specified Folder Path set Recursive to false, or to include all subfolders set Recursive to true.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Comparison Type

The Comparison Type specifying the rules used to match file or folder names against the given Search Pattern.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Paths

All Paths that match the specified Search Pattern based on the other specified options.

The Paths returned will be absolute paths, and based on the Folder Path provided (i.e. if a UNC path is specified, all returned paths will be UNC paths).

Data Type IList<String>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Paths with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
Thrown when Content Options is not one of the specified ContentOptions types (e.g. (ContentOptions)10).
Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
OperationFailedException The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to get the paths of files or folders in the Folder Path, or any of its subfolders if Recursive is true.
An unexpected error occurs when getting the paths of files or folders in the Folder Path, or any of its subfolders if Recursive is true.
PropertyEmptyException Thrown when Folder Path is empty (i.e. "").
PropertyNullException Thrown when Folder Path is null.
RegexMatchTimeoutException Thrown when using Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and the Search Pattern is not a valid regex (e.g. ().

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

Null or empty Search Pattern

A null or empty (i.e. "") Search Pattern means match any name; all additional block options such as Content Options etc. still take effect.

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Handling of Exceptions

If an exception occurs when trying to match a file or folder name, it will be recorded and the block will continue processing the remaining files or folders. Once all files or folders are processed, recorded exceptions will be thrown within an OperationFailedException.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.7.10 - Get Folder Information

Get information about a folder (i.e. folder attributes, created, accessed and modified dates etc.).

6.3.7.10.1 - Get Folder Information

Gets information about a folder (e.g. folder attributes, created, accessed, modified dates etc.) at the specified folder path.
Icon

Get Folder Information

(Cortex.Blocks.FilesAndFolders.GetFolderInformation.GetFolderInformationBlock)

Description

Gets Folder Information about a folder (e.g. folder attributes, created, accessed, modified dates etc.) at the specified Folder Path.

Examples

Get folder information

This example will get information about "C:\Source\Folder".

In this example assume "C:\Source\Folder":

  • Is on a server where local time and UTC time are the same (e.g. in UK).
  • Was created at 10.00am on the 1st January 2021.
  • Was last modified at 10.00am on the 1st January 2021.
  • Was last accessed at 1.00pm on the 10th January 2021.
  • Contains a single file named "File.txt" which is 100 bytes in size.
  • Contains a single empty folder named "SubFolder".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Folder Information ($)FolderInformation, with no value ($)FolderPath is a variable that will be set to a FolderInformation value

Result

Getting folder information for "C:\Source\Folder" results in the variable ($)FolderInformation being updated to the following:

{
    "FileCount": 1,
    "FolderCount": 1,
    "TotalItemCount": 2,
    "Path": "C:\\Source\\Folder",
    "Name": "Test",
    "ParentRoot": "C:\\",
    "ParentPath": "C:\\Source",
    "SizeInBytes": 100,
    "IsArchive": false,
    "IsCompressed": false,
    "IsEncrypted": false,
    "IsHidden": false,
    "IsNormal": false,
    "IsTemporary": false,
    "IsReadOnly": false,
    "IsSystem": false,
    "CreationTimeLocal": "2021-01-01T10:00:00+00:00",
    "CreationTimeUtc": "2021-01-01T10:00:00Z",
    "LastAccessTimeLocal": "2021-01-10T13:00:00+00:00",
    "LastAccessTimeUtc": "2021-01-10T13:00:00Z",
    "LastWriteTimeLocal": "2021-01-01T10:00:00+00:00",
    "LastWriteTimeUtc": "2021-01-01T10:00:00Z"
}

Properties

Folder Path

The Folder Path to get the Folder Information of.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Folder Information

The Folder Information retrieved from the folder at the specified Folder Path.

Folder Information includes folder attributes, create, access and write dates, path details and folder and file counts.

For more information see the example above, or the FolderInformation data type.

Data Type FolderInformation
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)FolderInformation with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
OperationFailedException The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to get information about the folder at the Folder Path.
An unexpected error occurs when getting information for the folder at the Folder Path or any of its content.
PropertyEmptyException Thrown when Folder Path is empty (i.e. "").
PropertyNullException Thrown when Folder Path is null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

6.3.7.11 - Move File(s)

Move a file or multiple files.

6.3.7.11.1 - Move File

Moves a file at the specified file path to the given destination path.
Icon

Move File

(Cortex.Blocks.FilesAndFolders.MoveFile.MoveFileBlock)

Description

Moves a file at the specified File Path to the given Destination Path, with an option to Overwrite the file if it already exists.

Examples

Move a file to a folder keeping the same file name

This example will move "C:\Source\OriginalFile.txt" to "C:\Destination", with the same file name of "OriginalFile.txt".

In this example assume "C:\Destination" does not already contain a file named "OriginalFile.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\OriginalFile.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Moving "C:\Source\OriginalFile.txt" to "C:\Destination" that does not already contain a file named "OriginalFile.txt" will:

  • Move "C:\Source\OriginalFile.txt" to "C:\Destination\OriginalFile.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move a file to a folder with a new name

This example will move "C:\Source\OriginalFile.txt" to "C:\Destination", with a new file name of "NewFile.txt".

To rename the file when it is being moved, please note that the Destination Path must be a file path, rather than a folder path (e.g. "C:\Destination\NewFile.txt" rather than "C:\Destination").

In this example assume "C:\Destination" does not already contain a file named "NewFile.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\OriginalFile.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination\NewFile.txt" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Move "C:\Source\OriginalFile.txt" to the path "C:\Destination\NewFile.txt" that does not already exist will:

  • Move "C:\Source\OriginalFile.txt" to "C:\Destination\NewFile.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move a file to a folder overwriting any file that already exists with the same name

This example will move "C:\Source\FileAlreadyExists.txt" to "C:\Destination", with the same file name of "FileAlreadyExists.txt".

In this example assume "C:\Destination" already contains a file named "FileAlreadyExists.txt", so overwrite must be set to true to ensure the content of the existing file can be overwritten.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\FileAlreadyExists.txt" ($)FilePath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean

Result

Moving "C:\Source\FileAlreadyExists.txt" to "C:\Destination" and overwriting the existing file named "FileAlreadyExists.txt" will:

  • Overwrite the existing file at "C:\Destination\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists.txt".
    • The Date Created copied from "C:\Source\FileAlreadyExists.txt".
    • The Date Accessed copied from "C:\Source\FileAlreadyExists.txt"
    • The Date Modified copied from "C:\Source\FileAlreadyExists.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists.txt".

Properties

File Path

The File Path to move the file from.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Destination Path

The Destination Path to move the file to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path can either point to a folder or a file:

  • If it points to a folder, the moved file will have the name specified in the File Path.
  • If it points to a file, the moved file will have the name specified in the Destination Path.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the file in the Destination Path if it already exists.

If the file exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The Destination Path (if it points to a file), or the Destination Path (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The File Path does not exist.
The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path or Destination Path is invalid (for example, it is on an unmapped drive).
The file in the specified Destination Path exists and overwrite is false.
The file in the specified Destination Path exists, is read-only and overwrite is true.
The user the flow is executing as does not have the required permissions to move the file (e.g. not having read access to the File Path or write access to the Destination Path).
An unexpected error occurs when moving the file.
PropertyEmptyException Thrown when File Path or Destination Path are empty (i.e. "").
PropertyNullException Thrown when File Path or Destination Path are null.

Remarks

File and Folder Paths

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path and Destination Path need escaping

File Path and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\OriginalFile.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\OriginalFile.txt") and Destination Path (e.g. @"C:\Destination").

File Attributes

When moving a file from the File Path to the new Destination Path, all of the file’s attributes will also be moved.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

6.3.7.11.2 - Move Files

Moves files at the specified file paths to the given destination path.
Icon

Move Files

(Cortex.Blocks.FilesAndFolders.MoveFile.MoveFilesBlock)

Description

Moves files at the specified File Paths to the given Destination Path, with an option to Overwrite the files if they already exist.

Examples

Move files to a folder keeping the same file names

This example will move ["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"] to "C:\Destination", with the same file names of "OriginalFile1.txt" and "OriginalFile2.txt".

In this example assume "C:\Destination" does not already contain a file named "OriginalFile1.txt" or a file named "OriginalFile2.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\OriginalFile1.txt", @"C:\Source\OriginalFile2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean

Result

Moving ["C:\Source\OriginalFile1.txt", "C:\Source\OriginalFile2.txt"] to "C:\Destination" that does not already contain files named "OriginalFile1.txt" and "OriginalFile2.txt" will:

  • Move "C:\Source\OriginalFile1.txt" to "C:\Destination\OriginalFile1.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Move "C:\Source\OriginalFile2.txt" to "C:\Destination\OriginalFile2.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move files to a folder overwriting any files that already exists with the same names

This example will move ["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"] to "C:\Destination", with the same file names of "FileAlreadyExists1.txt" and "FileAlreadyExists2.txt".

In this example assume "C:\Destination" already contains a file named "FileAlreadyExists1.txt" and a file named "FileAlreadyExists2.txt", so overwrite must be set to true to ensure the content of the existing files can be overwritten.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\FileAlreadyExists1.txt", @"C:\Source\FileAlreadyExists2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean

Result

Moving ["C:\Source\FileAlreadyExists1.txt", "C:\Source\FileAlreadyExists2.txt"] to "C:\Destination" and overwriting the existing files named "FileAlreadyExists1.txt" and "FileAlreadyExists2.txt" will:

  • Overwrite the existing file at "C:\Destination\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists1.txt".
    • The Date Created copied from "C:\Source\FileAlreadyExists1.txt".
    • The Date Accessed copied from "C:\Source\FileAlreadyExists1.txt"
    • The Date Modified copied from "C:\Source\FileAlreadyExists1.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists1.txt".
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\FileAlreadyExists2.txt".
    • The Date Created copied from "C:\Source\FileAlreadyExists2.txt".
    • The Date Accessed copied from "C:\Source\FileAlreadyExists2.txt".
    • The Date Modified copied from "C:\Source\FileAlreadyExists2.txt".
    • The File Attributes copied from "C:\Source\FileAlreadyExists2.txt".

Properties

File Paths

The File Paths to move the files from.

Each file path in File Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePaths with no value

Destination Path

The Destination Path to move the files to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The moved files will have the names specified in the File Paths.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the files in the Destination Path if they already exist.

If any file exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path does not point to a folder.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The Destination Path (if it points to a file), or the Destination Path (if it points to a folder) plus the file name, exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException Any file path in File Paths is null or empty (i.e. ""). For more information, see Null or Empty File Paths
Any file path in File Paths is duplicated. For more information, see Duplicate File Paths
Any file path in File Paths does not exist.
Any file path in File Paths points to a folder.
Any file path in File Paths contains leading spaces.
Any file path in File Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
Any file path in File Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any file path in File Paths or Destination Path is invalid (for example, it is on an unmapped drive).
Any file path in File Paths exists in the specified Destination Path and overwrite is false.
Any file path in File Paths exists in the specified Destination Path with the same name, is read-only and overwrite is true.
The user the flow is executing as does not have the required permissions to move any file (e.g. not having read access to a file path in File Paths or write access to the Destination Path).
An unexpected error occurs when moving a file.
PropertyEmptyException Thrown when File Paths does not contain any items, or Destination Path is empty (i.e. "").
PropertyNullException Thrown when File Paths or Destination Path are null.

Remarks

File and Folder Paths

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Paths and Destination Path need escaping

Each file path in File Paths and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\OriginalFile.txt"), or
  • Prepending an @ character before the start of the file path (e.g. @"C:\Source\OriginalFile.txt") and Destination Path (e.g. @"C:\Destination").

File Attributes

When moving a file in the File Paths to the new Destination Path, all of the file’s attributes will also be moved.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Handling of Exceptions

If an exception occurs when trying to move a file in the File Paths, it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.12 - Move Folder(s)

Move a folder or folders.

6.3.7.12.1 - Move Folder

Moves a folder at the specified folder path to the given destination path.
Icon

Move Folder

(Cortex.Blocks.FilesAndFolders.MoveFolder.MoveFolderBlock)

Description

Moves a folder at the specified Folder Path to the given Destination Path, with an option to move the folder and its content, or just its Content Only.

An option can also be specified to Overwrite anything being moved that already exists in the Destination Path.

Examples

Move a folder and its content

This example will move "C:\Source\Folder" and its content to "C:\Destination".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".
  • "C:\Destination" does not already contain a folder named "Folder", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Moving "C:\Source\Folder" and its content to "C:\Destination" that does not already contain a folder named "Folder" will:

  • Move "C:\Source\Folder" to "C:\Destination\Folder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\SubFolder" to "C:\Destination\Folder\SubFolder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\File.txt" to "C:\Destination\Folder\File.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move a folder and its content, overwriting any content that already exists

This example will move "C:\Source\Folder" and its content to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • An empty sub-folder named "SubFolderAlreadyExists".
    • A file named "File.txt".
    • A file named "FileAlreadyExists.txt".
  • "C:\Destination" already contains a folder named "Folder", which already contains:
    • A folder named "SubFolderAlreadyExists".
    • A file named "FileAlreadyExists.txt".

Therefore, overwrite must be set to true to ensure the existing "SubFolderAlreadyExists" and "FileAlreadyExists.txt" can be overwritten.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Moving "C:\Source\Folder" and its content to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\Folder", "C:\Destination\Folder\SubFolderAlreadyExists" and "C:\Destination\Folder\FileAlreadyExists.txt" already exist will:

  • Overwrite the existing folder at "C:\Destination\Folder" with:
    • The Date Created left unchanged.
    • The Date Accessed set to the time the move occurred.
    • The Date Modified set to the time the move occurred.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\SubFolder" to "C:\Destination\Folder\SubFolder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\Folder\SubFolderAlreadyExists" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\File.txt" to "C:\Destination\Folder\File.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\Folder\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Created copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Accessed copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Modified copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The File attributes copied from "C:\Source\Folder\FileAlreadyExists.txt".

Move a folder’s content only

This example will move "C:\Source\Folder" content only to "C:\Destination".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".
  • "C:\Destination" does not already contain a folder named "SubFolder" or a file named "File.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Moving "C:\Source\Folder" content only to "C:\Destination" that does not already contain a folder named "SubFolder" or a file named "File.txt" will:

  • Move "C:\Source\Folder\SubFolder" to "C:\Destination\SubFolder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\File.txt" to "C:\Destination\File.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move a folder’s content only, overwriting any content that already exists

This example will move "C:\Source\Folder" content only to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • An empty sub-folder named "SubFolderAlreadyExists".
    • A file named "File.txt".
    • A file named "FileAlreadyExists.txt".
  • "C:\Destination" already contains:
    • A folder named "SubFolderAlreadyExists".
    • A file named "FileAlreadyExists.txt".

Therefore, overwrite must be set to true to ensure the existing "SubFolderAlreadyExists" and "FileAlreadyExists.txt" can be overwritten.

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Moving "C:\Source\Folder" content only to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\SubFolderAlreadyExists" and "C:\Destination\FileAlreadyExists.txt" already exist will:

  • Move "C:\Source\Folder\SubFolder" to "C:\Destination\SubFolder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder\File.txt" to "C:\Destination\File.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists.txt" with:
    • The content copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Created copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Accessed copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The Date Modified copied from "C:\Source\Folder\FileAlreadyExists.txt".
    • The File attributes copied from "C:\Source\Folder\FileAlreadyExists.txt".

Move a folder and its content to the same location but with a different name

If it is required to move a folder and its content into the same folder it is currently located in, but with a different name, then it is not possible to do with this block; the Rename Folder block must be used instead.


Move a folder and its content to a different location but with a different name

If it is required to move a folder and its content into a different folder than the one it is currently located in, but with a different name, it is not possible to do with a single block; you must use a combination of this block and the Rename Folder block.


Properties

Folder Path

The Folder Path to move the folder and/or its content from.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

Destination Path

The Destination Path to move the folder and/or its content to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The moved folders and files will have the same names as the folders and files moved.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the folder and/or contents being moved to in the Destination Path if they already exist.

If the folder and/or contents exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing folders and files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Content Only

Option to specify whether to move the folder and its content or just the Content Only.

To move the folder and its content, Content Only must be set to false; to move just the content, Content Only must be set to true.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path points to a file.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Destination Path exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The Folder Path does not exist.
The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path or Destination Path is a win32 device path (i.e starts with a "\\.\").
The Folder Path or Destination Path is invalid (for example, it is on an unmapped drive).
The Folder Path and Destination Path point to the same folder and Content Only is true.
The Folder Path is a child folder in the Destination Path and Content Only is false.
Any file being moved already exists in the specified Destination Path and overwrite is false.
Any file being moved already exists in the specified Destination Path, is read-only and overwrite is true.
The user the flow is executing as does not have the required permissions to move the folder or any of its content (e.g. not having read access to the Folder Path or its content, or write access to the Destination Path).
The operation is cyclic (e.g. moving a folder into one of its sub-folders).
An unexpected error occurs when moving the folder or any of its content.
PropertyEmptyException Thrown when Folder Path or Destination Path are empty (i.e. "").
PropertyNullException Thrown when Folder Path or Destination Path are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path and Destination Path need escaping

Folder Path and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source") and Destination Path (e.g. @"C:\Destination").

Folder Attributes

When moving the folder at the specified Folder Path or any folder under it to the new Destination Path, if the folder already exists in the destination its attributes remain unchanged.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

File Attributes

When moving a file under Folder Path to the new Destination Path, all of the file’s attributes are also moved.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Handling of Exceptions

If an exception occurs when trying to move Folder Path, an OperationFailedException will be thrown.

6.3.7.12.2 - Move Folders

Moves folders at the specified folder paths to the given destination path.
Icon

Move Folders

(Cortex.Blocks.FilesAndFolders.MoveFolder.MoveFoldersBlock)

Description

Moves folders at the specified Folder Paths to the given Destination Path, with an option to move the folders and their content, or just their Content Only.

An option can also be specified to Overwrite anything being moved that already exists in the Destination Path.

Examples

Move folders and their content

This example will move ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination".

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • A file named "File1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • A file named "File2.txt".
  • "C:\Destination" does not already contain a folder named "Folder1" or "Folder2", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Moving ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination" that does not already contain folders named "Folder1" and "Folder2" will:

  • Move "C:\Source\Folder1" to "C:\Destination\Folder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\SubFolder1" to "C:\Destination\Folder1\SubFolder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\File1.txt" to "C:\Destination\Folder1\File1.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Move "C:\Source\Folder2" to "C:\Destination\Folder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\SubFolder2" to "C:\Destination\Folder2\SubFolder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\File2.txt" to "C:\Destination\Folder2\File2.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move folders and their content, overwriting any content that already exists

This example will move ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • An empty sub-folder named "SubFolderAlreadyExists1".
    • A file named "File1.txt".
    • A file named "FileAlreadyExists1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • An empty sub-folder named "SubFolderAlreadyExists2".
    • A file named "File2.txt".
    • A file named "FileAlreadyExists2.txt".
  • "C:\Destination" already contains:
    • A folder named "Folder1", which already contains:
      • A folder named "SubFolderAlreadyExists1".
      • A file named "FileAlreadyExists1.txt".
    • A folder named "Folder2", which already contains:
      • A folder named "SubFolderAlreadyExists2".
      • A file named "FileAlreadyExists2.txt".

Therefore, overwrite must be set to true to ensure the existing folders and files can be overwritten.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value false ($)ContentOnly is a variable of type Boolean

Result

Moving ["C:\Source\Folder1", "C:\Source\Folder2"] and their content to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\Folder1", "C:\Destination\Folder1\SubFolderAlreadyExists1", "C:\Destination\Folder1\FileAlreadyExists1.txt", "C:\Destination\Folder2", "C:\Destination\Folder2\SubFolderAlreadyExists2" and "C:\Destination\Folder2\FileAlreadyExists2.txt" already exist will:

  • Overwrite the existing folder at "C:\Destination\Folder1" with:
    • The Date Created left unchanged.
    • The Date Accessed set to the time the move occurred.
    • The Date Modified set to the time the move occurred.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\SubFolder1" to "C:\Destination\Folder1\SubFolder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\Folder1\SubFolderAlreadyExists1" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\File1.txt" to "C:\Destination\Folder1\File1.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\Folder1\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Created copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Accessed copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Modified copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The File attributes copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
  • Overwrite the existing folder at "C:\Destination\Folder2" with:
    • The Date Created left unchanged.
    • The Date Accessed set to the time the move occurred.
    • The Date Modified set to the time the move occurred.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\SubFolder2" to "C:\Destination\Folder2\SubFolder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\Folder2\SubFolderAlreadyExists2" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\File2.txt" to "C:\Destination\Folder2\File2.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\Folder2\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Created copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Accessed copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Modified copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The File attributes copied from "C:\Source\Folder2\FileAlreadyExists2.txt".

Move the folders’ content only

This example will move ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination".

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • A file named "File1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • A file named "File2.txt".
  • "C:\Destination" does not already contain a folder named "SubFolder1" or "SubFolder2" or a file named "File1.txt" or "File2.txt", so overwrite can be set to either true or false and it will still work.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Moving ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination" that does not already contain a folder named "SubFolder1" or "SubFolder2" or a file named "File1.txt" or "File2.txt" will:

  • Move "C:\Source\Folder1\SubFolder1" to "C:\Destination\SubFolder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\File1.txt" to "C:\Destination\File1.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Move "C:\Source\Folder2\SubFolder2" to "C:\Destination\SubFolder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\File2.txt" to "C:\Destination\File2.txt" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.

Move folders’ content only, overwriting any content that already exists

This example will move ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination", overwriting any content that already exists.

In this example assume:

  • "C:\Source\Folder1" contains:
    • An empty sub-folder named "SubFolder1".
    • An empty sub-folder named "SubFolderAlreadyExists1".
    • A file named "File1.txt".
    • A file named "FileAlreadyExists1.txt".
  • "C:\Source\Folder2" contains:
    • An empty sub-folder named "SubFolder2".
    • An empty sub-folder named "SubFolderAlreadyExists2".
    • A file named "File2.txt".
    • A file named "FileAlreadyExists2.txt".
  • "C:\Destination" already contains:
    • A folder named "SubFolderAlreadyExists1".
    • A folder named "SubFolderAlreadyExists2".
    • A file named "FileAlreadyExists1.txt".
    • A file named "FileAlreadyExists2.txt".

Therefore, overwrite must be set to true to ensure the existing folders and files can be overwritten.

Properties

Property Value Notes
Folder Paths ($)FolderPaths, with value [@"C:\Source\Folder1", @"C:\Source\Folder2"] ($)FolderPaths is a variable of type IEnumerable<String>
Destination Path ($)DestinationPath, with value @"C:\Destination" ($)DestinationPath is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Content Only ($)ContentOnly, with value true ($)ContentOnly is a variable of type Boolean

Result

Moving ["C:\Source\Folder1", "C:\Source\Folder2"] content only to "C:\Destination" with the Overwrite option set to true, and where "C:\Destination\SubFolderAlreadyExists1", "C:\Destination\SubFolderAlreadyExists2", "C:\Destination\FileAlreadyExists1.txt" and "C:\Destination\FileAlreadyExists2.txt" already exist will:

  • Move "C:\Source\Folder1\SubFolder1" to "C:\Destination\SubFolder1" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists1" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder1\File1.txt" to "C:\Destination\File1.txt" with:
    • The content copied left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists1.txt" with:
    • The content copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Created copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Accessed copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The Date Modified copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
    • The File attributes copied from "C:\Source\Folder1\FileAlreadyExists1.txt".
  • Move "C:\Source\Folder2\SubFolder2" to "C:\Destination\SubFolder2" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Overwrite the existing folder at "C:\Destination\SubFolderAlreadyExists2" with:
    • The content left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • Move "C:\Source\Folder2\File2.txt" to "C:\Destination\File2.txt" with:
    • The content copied left unchanged.
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The File attributes left unchanged.
  • Overwrite the existing file at "C:\Destination\FileAlreadyExists2.txt" with:
    • The content copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Created copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Accessed copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The Date Modified copied from "C:\Source\Folder2\FileAlreadyExists2.txt".
    • The File attributes copied from "C:\Source\Folder2\FileAlreadyExists2.txt".

Move folders and their content to the same location but with a different name

If it is required to move folders and their content into the same folder they are currently located in, but with a different name, then it is not possible to do with this block; the Rename Folder block must be used instead.


Move folders and their content to a different location but with a different name

If it is required to move folders and their content into a different folder than the one they are currently located in, but with a different name, it is not possible to do with a single block; you must use a combination of this block and the Rename Folder block.


Properties

Folder Paths

The Folder Paths to move the folders and/or their content from.

Each folder path in Folder Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPaths with no value

Destination Path

The Destination Path to move the folders and/or their content to.

The Destination Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

The Destination Path must point to a folder, otherwise an InvalidPathException will be thrown.

The moved folders and files will have the same names as the folders and files copied.

Any non-existing folders within the Destination Path will be automatically created.

For information about the supported file and folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Overwrite

Option to Overwrite the folders and/or contents being moved to in the Destination Path if they already exist.

If any of the folders and/or contents exists, Overwrite must be set to true, otherwise an OperationFailedException will be thrown. By default, this is set to false to avoid implicit and accidental overwriting of existing folders and files.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Content Only

Option to specify whether to move the folders and their content or just the Content Only.

To move the folders and their content, Content Only must be set to false; to move just the content, Content Only must be set to true.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPathException The Destination Path points to a file.
The Destination Path contains leading spaces.
The Destination Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Destination Path exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException Any folder path in Folder Paths is null or empty (i.e. ""). For more information, see Null or Empty Folder Paths
Any folder path in Folder Paths is duplicated. For more information, see Duplicate Folder Paths
Any folder path in Folder Paths does not exist.
Any folder path in Folder Paths points to a file.
Any folder path in Folder Paths contains leading spaces.
Any folder path in Folder Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
Any folder path in Folder Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any folder path in Folder Paths or Destination Path is a win32 device path (i.e starts with a "\\.\").
Any folder path in Folder Paths or Destination Path is invalid (for example, it is on an unmapped drive).
Any folder path in Folder Paths and Destination Path point to the same folder and Content Only is true.
Any folder path in Folder Paths is a child folder in the Destination Path and Content Only is false.
Any file being moved already exists in the specified Destination Path and overwrite is false.
Any file being moved already exists in the specified Destination Path, is read-only and overwrite is true.
The user the flow is executing as does not have the required permissions to move the folder or any of its content (e.g. not having read access to any of the folders in Folder Paths or its content, or write access to the Destination Path).
The operation is cyclic (e.g. moving a folder into one of its sub-folders).
An unexpected error occurs when moving a folder or any of its content.
PropertyEmptyException Thrown when Folder Paths does not contain any items, or Destination Path are empty (i.e. "").
PropertyNullException Thrown when Folder Paths or Destination Path are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path and Destination Path need escaping

Each folder paths in Folder Paths and Destination Path require \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the folder path (e.g. @"C:\Source") and Destination Path (e.g. @"C:\Destination").

Folder Attributes

When moving the folders at the specified Folder Paths or any folder under them to the new Destination Path, if the folder already exists in the destination its attributes remain unchanged.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

File Attributes

When moving a file under any of the Folder Paths to the new Destination Path, all of the file’s attributes are also moved.

For information about the file attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

Conflicting Content

If two or more paths in the specified Folder Paths contain content (folders or files) with the same name, and Overwrite and Content Only are true:

  • The attributes of the folder/file in the Destination Path will be that of the first one moved.
  • For files, the content of the file in the Destination Path will be that of the last one moved.

Handling of Exceptions

If an exception occurs when trying to move a folder in Folder Paths, it will be recorded and the block will continue processing the remaining folders. Once all folders are processed, recorded exceptions will be thrown within an OperationFailedException.

6.3.7.13 - Read File

Read the content of a file.

6.3.7.13.1 - Read All Lines

Reads all lines from a file at the specified file path.
Icon

Read All Lines

(Cortex.Blocks.FilesAndFolders.ReadFile.ReadAllLinesBlock)

Description

Reads all Lines from a file at the specified File Path, with an option to explicitly specify the Encoding of the file if needed.

Examples

Read all lines

This example will read all lines from "C:\Source\File.txt", automatically detecting the encoding.

In this example assume "C:\Source\File.txt" is a UTF-8 encoded file containing 10 lines:

This is Line 1
This is Line 2
This is Line 3
This is Line 4
This is Line 5
This is Line 6
This is Line 7
This is Line 8
This is Line 9
This is Line 10

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Lines ($)Lines, with no value ($)Lines is a variable that will be set to an IList<String>

Result

Reading all lines from "C:\Source\File.txt" results in the variable ($)Lines being updated to the following:

[
    "This is Line 1", 
    "This is Line 2", 
    "This is Line 3", 
    "This is Line 4", 
    "This is Line 5",
    "This is Line 6",
    "This is Line 7",
    "This is Line 8",
    "This is Line 9",
    "This is Line 10"
]

Properties

File Path

The File Path to read all lines of the file from.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Encoding

Option to specify the Encoding that should be used to read the file.

Most of the time Encoding can be left as null; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned Lines are not in the correct format because the block was unable to detect the encoding of the file, it is possible to specify the Encoding explicitly using this property.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Lines

All Lines that were read from the file.

A line is defined as a sequence of characters followed by a carriage return (i.e. \r), a line feed (i.e. \n), or a carriage return immediately followed by a line feed. The resulting Lines do not contain the terminating carriage returns and/or line feeds.

Data Type IList<String>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Lines with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException The File Path does not exist.
The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to read the file.
An unexpected error occurs when reading the file.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

6.3.7.13.2 - Read All Text

Reads all text from a file at the specified file path.
Icon

Read All Text

(Cortex.Blocks.FilesAndFolders.ReadFile.ReadAllTextBlock)

Description

Reads all Text from a file at the specified File Path, with an option to explicitly specify the Encoding of the file if needed.

Examples

Read all text

This example will read all text from "C:\Source\File.txt", automatically detecting the encoding.

In this example assume "C:\Source\File.txt" is a UTF-8 encoded file containing the following text:

This is Line 1
This is Line 2
This is Line 3
This is Line 4
This is Line 5
This is Line 6
This is Line 7
This is Line 8
This is Line 9
This is Line 10

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Text ($)Text, with no value ($)Text is a variable that will be set to a String

Result

Reading all text from "C:\Source\File.txt" results in the variable ($)Text being updated to the following:

"This is Line 1
This is Line 2
This is Line 3
This is Line 4
This is Line 5
This is Line 6
This is Line 7
This is Line 8
This is Line 9
This is Line 10"

Properties

File Path

The File Path to read all text of the file from.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Encoding

Option to specify the Encoding that should be used to read the file.

Most of the time Encoding can be left as null; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned Text are not in the correct format because the block was unable to detect the encoding of the file, it is possible to specify the Encoding explicitly using this property.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Text

All Text that was read from the file.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException The File Path does not exist.
The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to read the file.
An unexpected error occurs when reading the file.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

6.3.7.14 - Rename Folder

Rename a folder.

6.3.7.14.1 - Rename Folder

Renames a folder at the specified folder path to a new name.
Icon

Rename Folder

(Cortex.Blocks.FilesAndFolders.RenameFolder.RenameFolderBlock)

Description

Renames a folder at the specified Folder Path to a New Name.

Examples

Rename a folder

This example will rename "C:\Source\Folder" to "C:\Source\RenamedFolder".

In this example assume:

  • "C:\Source\Folder" contains:
    • An empty sub-folder named "SubFolder".
    • A file named "File.txt".

Properties

Property Value Notes
Folder Path ($)FolderPath, with value @"C:\Source\Folder" ($)FolderPath is a variable of type String
New Name ($)NewName, with value "RenamedFolder" ($)NewName is a variable of type String

Result

Renaming "C:\Source\Folder" to "RenamedFolder" will:

  • Rename the existing folder at "C:\Source\Folder" to "C:\Source\RenamedFolder" with:
    • The Date Created left unchanged.
    • The Date Accessed left unchanged.
    • The Date Modified left unchanged.
    • The Folder attributes left unchanged.
  • "SubFolder" and "File.txt" will be located under "C:\Source\RenamedFolder" and their names, dates, attributes and content will be left unchanged.

Other Move Operations

If any other folder move operation is required, the Move Folder or Move Folders blocks must be used instead.


Properties

Folder Path

The Folder Path of the folder to rename.

The Folder Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FolderPath with no value

New Name

The New Name to rename the folder to.

The New Name is case-insensitive and any trailing spaces will be automatically removed.

The New Name must be a valid folder name, otherwise an InvalidFolderNameException will be thrown.

For information about valid folder names, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidFolderNameException A folder or file with the New Name already exists.
The New Name contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /).
The New Name exceeds the system-defined maximum length (typically 32,767 characters).
OperationFailedException The Folder Path does not exist.
The Folder Path points to a file.
The Folder Path contains leading spaces.
The Folder Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any folder names.
The Folder Path exceeds the system-defined maximum length (typically 32,767 characters).
The Folder Path is a win32 device path (i.e starts with a "\\.\").
The Folder Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to rename the folder or any of its content (e.g. not having read access to the Folder Path or its content, or write access to the parent of Folder Path.
An unexpected error occurs when renaming the folder.
PropertyEmptyException Thrown when Folder Path or New Name are empty (i.e. "").
PropertyNullException Thrown when Folder Path or New Name are null.

Remarks

Folder Paths

For information about the supported folder path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

Folder Path needs escaping

Folder Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\"), or
  • Prepending an @ character before the start of the Folder Path (e.g. @"C:\Source").

Folder Attributes

When renaming the folder at the specified Folder Path all of the folder’s attributes are left unchanged.

For information about the folder attributes (i.e. ReadOnly, Hidden, Archive etc.), please see File & Folder Attributes.

6.3.7.15 - Search File(s)

Search a file or multiple files.

6.3.7.15.1 - Search File

Searches a file at a specified file path for a matching search pattern.
Icon

Search File

(Cortex.Blocks.FilesAndFolders.SearchFile.SearchFileBlock)

Description

Searches the file at the specified File Path for text that matches a given Search Pattern.

Results are returned as a list of Matches.

Additional options can be specified:

  • Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search.
  • Encoding can be specified if needed to explicitly state the encoding that should be used to read and search the file.
  • A Comparison Type option can specified to choose how it is determined whether text matches the Search Pattern (e.g. whether the search is case-sensitive or case-insensitive).

Examples

Get matches for a given text

This example will get all matches in the file "C:\Source\File.txt" that match the text "error".

It will perform a case-insensitive search, and let the block determine the encoding of the file automatically.

In this example assume "C:\Source\File.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Search Pattern ($)SearchPattern, with value "error" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IList<FileMatch> value

Result

Searching "C:\Source\File.txt" for all text matching "error" (case-insensitive), results in the variable ($)Matches being updated to the following:

[
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 1,
    "Value": "Error",
    "Index": 0,
    "Length": 5,
    "Groups": {}
  },
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 4,
    "Value": "Error",
    "Index": 0,
    "Length": 5,
    "Groups": {}
  },
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 4,
    "Value": "error",
    "Index": 19,
    "Length": 5,
    "Groups": {}
  }
]

Get matches for a given pattern

This example will get all matches in the file "C:\Source\File.txt" that match the pattern "Uptime is * hours.".

It will perform a case-sensitive search, and let the block determine the encoding of the file automatically.

In this example assume "C:\Source\File.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Search Pattern ($)SearchPattern, with value "Uptime is * hours." ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IList<FileMatch> value

Result

Searching "C:\Source\File.txt" for all text matching the pattern "Uptime is * hours." (case-sensitive), results in the variable ($)Matches being updated to the following:

[
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 2,
    "Value": "Uptime is 2 hours.",
    "Index": 13,
    "Length": 18,
    "Groups": {}
  },
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 3,
    "Value": "Uptime is 3 hours.",
    "Index": 13,
    "Length": 18,
    "Groups": {}
  }
]

Get matches for a given regex

This example will get all matches in the file "C:\Source\File.txt" that match the regex "^Error:.*$".

It will perform a case-sensitive search, explicitly specify the encoding of the file as UTF-8 and will match any line that starts with "Error:".

In this example assume "C:\Source\File.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Search Pattern ($)SearchPattern, with value "^Error:.*$" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value Encoding.UTF8 ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IList<FileMatch> value

Result

Searching "C:\Source\File.txt" for all text matching the regex "^Error:.*$" (case-sensitive), results in the variable ($)Matches being updated to the following:

[
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 1,
    "Value": "Error: Failed to determine uptime.",
    "Index": 0,
    "Length": 34,
    "Groups": {}
  },
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 4,
    "Value": "Error: An terminal error has occurred. The service will restart now.",
    "Index": 0,
    "Length": 68,
    "Groups": {}
  }
]

Properties

File Path

The File Path to search for text that matches a given Search Pattern.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Search Pattern

The Search Pattern which text must match to be included in the returned Matches.

A null or empty (i.e. "") Search Pattern means match anything; all additional block options such as Search Options etc. still take effect.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Search Options

Search Options can be specified to choose whether Search Pattern should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Encoding

Option to specify the Encoding that should be used to read and search the file.

Most of the time Encoding can be left as null; allowing the block to automatically attempt to detect the encoding of the file based on the presence of byte order marks. However, if it is found that the returned Matches are not correct because the block was unable to detect the encoding of the file, it is possible to specify the Encoding explicitly using this property.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Comparison Type

The Comparison Type specifying the rules used to match text against the given Search Pattern.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Matches

Matches containing a FileMatch for every text that matches the specified Search Pattern based on the other specified options.

A basic example with a single FileMatch can be seen below:

[
  {
    "FilePath": "C:\\Source\\File.txt",
    "Line": 1,
    "Value": "Error: Failed to determine uptime.",
    "Index": 0,
    "Length": 34,
    "Groups": {}
  }
]

For more information see the example above, or the FileMatch data type.

Data Type IList<FileMatch>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Matches with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException The File Path does not exist.
The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to search the File Path.
An unexpected error occurs when searching the File Path.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.
RegexMatchTimeoutException Thrown when using Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and the Search Pattern is not a valid regex (e.g. ().

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

Null or empty Search Pattern

A null or empty (i.e. "") Search Pattern means match anything; all additional block options such as Search Options etc. still take effect.

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Known Limitations

  • The text in the file at the specified File Path is searched line-by-line. As a result, when using SearchOptions.Regex the in-line s regex character is not supported.
  • If the text in the file at the specified File Path ends with a blank line (0 length) that line will not be read and therefore not matched against.
  • If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.7.15.2 - Search Files

Searches files at the specified file paths for a matching search pattern.
Icon

Search Files

(Cortex.Blocks.FilesAndFolders.SearchFile.SearchFilesBlock)

Description

Searches the files at the specified File Paths for text that matches a given Search Pattern.

Results are returned as Matches.

Additional options can be specified:

  • Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search.
  • Encoding can be specified if needed to explicitly state the encoding that should be used to read and search the files.
  • A Comparison Type option can specified to choose how it is determined whether text matches the Search Pattern (e.g. whether the search is case-sensitive or case-insensitive).

Examples

Get matches for a given text

This example will get all matches in the files ["C:\Source\File1.txt", "C:\Source\File2.txt"] that match the text "error".

It will perform a case-insensitive search, and let the block determine the encoding of the files automatically.

In this example assume "C:\Source\File1.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

and "C:\Source\File2.txt" contains the following text:

Information: Uptime is 1 hour.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: Failed to determine uptime.
Error: Failed to determine uptime.
Information: Uptime is 6 hours.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\File1.txt", @"C:\Source\File2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Search Pattern ($)SearchPattern, with value "error" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IDictionary<String, IList<FileMatch>> value

Result

Searching "C:\Source\File.txt" for all text matching "error" (case-insensitive), results in the variable ($)Matches being updated to the following:

{
  "C:\\Source\\File1.txt" : [
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 1,
                                "Value": "Error",
                                "Index": 0,
                                "Length": 5,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 4,
                                "Value": "Error",
                                "Index": 0,
                                "Length": 5,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 4,
                                "Value": "error",
                                "Index": 19,
                                "Length": 5,
                                "Groups": {}
                              }
                            ],
  "C:\\Source\\File2.txt" : [
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 4,
                                "Value": "Error",
                                "Index": 0,
                                "Length": 5,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 5,
                                "Value": "Error",
                                "Index": 0,
                                "Length": 5,
                                "Groups": {}
                              }
                            ]                            
}

Get matches for a given pattern

This example will get all matches in the files ["C:\Source\File1.txt", "C:\Source\File2.txt"] that match the pattern "Uptime is * hour?.".

It will perform a case-sensitive search, and let the block determine the encoding of the files automatically.

In this example assume "C:\Source\File1.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

and "C:\Source\File2.txt" contains the following text:

Information: Uptime is 1 hour.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: Failed to determine uptime.
Error: Failed to determine uptime.
Information: Uptime is 6 hours.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\File1.txt", @"C:\Source\File2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Search Pattern ($)SearchPattern, with value "Uptime is * hour?." ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IDictionary<String, IList<FileMatch>> value

Result

Searching the files ["C:\Source\File1.txt", "C:\Source\File2.txt"] for all text matching the pattern "Uptime is * hour?." (case-sensitive), results in the variable ($)Matches being updated to the following:

{
  "C:\\Source\\File1.txt" : [
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 2,
                                "Value": "Uptime is 2 hours.",
                                "Index": 13,
                                "Length": 18,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 3,
                                "Value": "Uptime is 3 hours.",
                                "Index": 13,
                                "Length": 18,
                                "Groups": {}
                              }
                            ],
  "C:\\Source\\File2.txt" : [
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 1,
                                "Value": "Uptime is 1 hour.",
                                "Index": 13,
                                "Length": 17,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 2,
                                "Value": "Uptime is 2 hours.",
                                "Index": 13,
                                "Length": 18,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 3,
                                "Value": "Uptime is 3 hours.",
                                "Index": 13,
                                "Length": 18,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 6,
                                "Value": "Uptime is 6 hours.",
                                "Index": 13,
                                "Length": 18,
                                "Groups": {}
                              }
                            ]                            
}

Get matches for a given regex

This example will get all matches in the files ["C:\Source\File1.txt", "C:\Source\File2.txt"] that match the regex "^Error:.*$".

It will perform a case-sensitive search, explicitly specify the encoding of the files as UTF-8 and will match any lines that start with "Error:".

In this example assume "C:\Source\File1.txt" contains the following text:

Error: Failed to determine uptime.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: An terminal error has occurred. The service will restart now.

and "C:\Source\File2.txt" contains the following text:

Information: Uptime is 1 hour.
Information: Uptime is 2 hours.
Information: Uptime is 3 hours.
Error: Failed to determine uptime.
Error: Failed to determine uptime.
Information: Uptime is 6 hours.

Properties

Property Value Notes
File Paths ($)FilePaths, with value [@"C:\Source\File1.txt", @"C:\Source\File2.txt"] ($)FilePaths is a variable of type IEnumerable<String>
Search Pattern ($)SearchPattern, with value "^Error:.*$" ($)SearchPattern is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Encoding ($)Encoding, with value Encoding.UTF8 ($)Encoding is a variable of type Encoding
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Matches ($)Matches, with no value ($)Matches is a variable that will be set to an IDictionary<String, IList<FileMatch>> value

Result

Searching the files ["C:\Source\File1.txt", "C:\Source\File2.txt"] for all text matching the regex "^Error:.*$" (case-sensitive), results in the variable ($)Matches being updated to the following:

{
  "C:\\Source\\File1.txt" : [
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 1,
                                "Value": "Error: Failed to determine uptime.",
                                "Index": 0,
                                "Length": 34,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 4,
                                "Value": "Error: An terminal error has occurred. The service will restart now.",
                                "Index": 0,
                                "Length": 68,
                                "Groups": {}
                              }
                            ],
  "C:\\Source\\File2.txt" : [
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 4,
                                "Value": "Error: Failed to determine uptime.",
                                "Index": 0,
                                "Length": 34,
                                "Groups": {}
                              },
                              {
                                "FilePath": "C:\\Source\\File2.txt",
                                "Line": 5,
                                "Value": "Error: Failed to determine uptime.",
                                "Index": 0,
                                "Length": 34,
                                "Groups": {}
                              }
                            ]                            
}

Properties

File Paths

The File Paths to search for text that matches a given Search Pattern.

Each file path in File Paths is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePaths with no value

Search Pattern

The Search Pattern which text must match to be included in the returned Matches.

A null or empty (i.e. "") Search Pattern means match anything; all additional block options such as Search Options etc. still take effect.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to "")

Search Options

Search Options can be specified to choose whether Search Pattern should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Encoding

Option to specify the Encoding that should be used to read and search the files.

Most of the time Encoding can be left as null; allowing the block to automatically attempt to detect the encoding of the files based on the presence of byte order marks. However, if it is found that the returned Matches are not correct because the block was unable to detect the encoding of the files, it is possible to specify the Encoding explicitly using this property.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Comparison Type

The Comparison Type specifying the rules used to match text against the given Search Pattern.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Matches

Matches containing an entry for each file in File Paths.

The key of each entry is the file path, and the value contains a FileMatch for every text in the file path that matches the specified Search Pattern based on the other specified options.

A basic example with a single file path and a single FileMatch can be seen below:

{
  "C:\\Source\\File1.txt" : [
                              {
                                "FilePath": "C:\\Source\\File1.txt",
                                "Line": 1,
                                "Value": "Error: Failed to determine uptime.",
                                "Index": 0,
                                "Length": 34,
                                "Groups": {}
                              }
                            ]                          
}

For more information see the example above, or the FileMatch data type.

Data Type IDictionary<String, IList<FileMatch>>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Matches with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException Any file path in File Paths is null or empty (i.e. ""). For more information, see Null or Empty File Paths
Any file path in File Paths is duplicated. For more information, see Duplicate File Paths
Any file path in File Paths does not exist.
Any file path in File Paths points to a folder.
Any file path in File Paths contains leading spaces.
Any file path in File Paths contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
Any file path in File Paths exceeds the system-defined maximum length (typically 32,767 characters).
Any file path in File Paths is invalid (for example, it is on an unmapped drive).
The user the flow is executing as does not have the required permissions to search a file path in File Paths.
An unexpected error occurs when searching any file path in File Paths.
PropertyEmptyException Thrown when File Paths does not contain any items.
PropertyNullException Thrown when File Paths is null.
RegexMatchTimeoutException Thrown when using Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and the Search Pattern is not a valid regex (e.g. ().

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Paths needs escaping

Each file path in File Paths requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Paths (e.g. @"C:\Source\File.txt").

Null or empty Search Pattern

A null or empty (i.e. "") Search Pattern means match anything; all additional block options such as Search Options etc. still take effect.

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Handling of Exceptions

If an exception occurs when trying to search a file in the File Paths, it will be recorded and the block will continue processing the remaining files. Once all files are processed, recorded exceptions will be thrown within an OperationFailedException.

Known Limitations

  • The text in the files at the specified File Paths is searched line-by-line. As a result, when using SearchOptions.Regex the in-line s regex character is not supported.
  • If the text in the files at the specified File Paths ends with a blank line (0 length) that line will not be read and therefore not matched against.
  • If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.7.16 - Write File

Write the content of a file.

6.3.7.16.1 - Write All Lines

Writes all specified lines to a file at the given file path.
Icon

Write All Lines

(Cortex.Blocks.FilesAndFolders.WriteFile.WriteAllLinesBlock)

Description

Writes all specified Lines to the end of the file at the given File Path, with an option to explicitly specify the Encoding to write the file as if needed.

An option can also be specified to Overwrite rather than append to the file.

Examples

Write all lines, appending to the end of the file

This example will append ["New Line 1", "New Line 2"] to "C:\Source\File.txt", using UTF-8 encoding without a byte order mark.

In this example assume "C:\Source\File.txt" contains 2 lines:

Original Line 1
Original Line 2

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Lines ($)Lines, with value ["New Line 1", "New Line 2"] ($)Lines is a variable of type IEnumerable<String>
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding

Result

Writing ["New Line 1", "New Line 2"] to "C:\Source\File.txt" results in the content being updated to the following:

Original Line 1
Original Line 2
New Line 1
New Line 2

Write all lines, overwriting the file content

This example will overwrite the content of "C:\Source\File.txt" with ["New Line 1", "New Line 2"], using UTF-8 encoding without a byte order mark.

In this example assume "C:\Source\File.txt" contains 2 lines:

Original Line 1
Original Line 2

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Lines ($)Lines, with value ["New Line 1", "New Line 2"] ($)Lines is a variable of type IEnumerable<String>
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding

Result

Overwriting "C:\Source\File.txt" with ["New Line 1", "New Line 2"] results in the content being updated to the following:

New Line 1
New Line 2

Properties

File Path

The File Path to write all Lines to.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

If the file does not exist at the File Path, a new file is created, and any non-existing folders will also be created.

If the file already exists at the File Path and Overwrite is:

  • true, the Lines overwrite the existing file content.
  • false, the Lines are appended to the existing file content.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Lines

The Lines to write to the file.

Lines can be null or empty (i.e. "").

If Lines is null or empty (i.e. "") and Overwrite is:

  • true, a blank file will be written.
  • false, nothing is written.

If Lines contains an entry that is null or empty (i.e. "") a blank line will be written for that entry.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Lines with no value

Overwrite

Option to Overwrite the file content with the Lines, rather than appending them.

By default, this is set to false to avoid implicit and accidental overwriting of the file content.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Encoding

Option to specify the Encoding that should be used to write the file.

If the Encoding is left as null, the Lines will be written using UTF-8 encoding without a byte order mark.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The file at the specified File Path is hidden or is a System file, and overwrite is true.
The file at the specified File Path is a read-only file.
The user the flow is executing as does not have the required permissions to write to the file.
An unexpected error occurs when writing the file.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

6.3.7.16.2 - Write All Text

Writes all specified text to a file at the given file path.
Icon

Write All Text

(Cortex.Blocks.FilesAndFolders.WriteFile.WriteAllTextBlock)

Description

Writes all specified Text to the end of the file at the given File Path, with an option to explicitly specify the Encoding to write the file as if needed.

An option can also be specified to Overwrite rather than append to the file.

Examples

Write all text, appending to the end of the file

This example will append "New Line 1\r\nNew Line 2" to "C:\Source\File.txt", using UTF-8 encoding without a byte order mark.

In this example assume "C:\Source\File.txt" contains the following text:

Original Line 1
Original Line 2

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Text ($)Text, with value "New Line 1\r\nNew Line 2" ($)Text is a variable of type String
Overwrite ($)Overwrite, with value false ($)Overwrite is a variable of type Boolean
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding

Result

Writing "New Line 1\r\nNew Line 2" to "C:\Source\File.txt" results in the content being updated to the following:

Original Line 1
Original Line 2
New Line 1
New Line 2

Write all text, overwriting the file content

This example will overwrite the content of "C:\Source\File.txt" with "New Line 1\r\nNew Line 2", using UTF-8 encoding without a byte order mark.

In this example assume "C:\Source\File.txt" contains the following text:

Original Line 1
Original Line 2

Properties

Property Value Notes
File Path ($)FilePath, with value @"C:\Source\File.txt" ($)FilePath is a variable of type String
Text ($)Text, with value "New Line 1\r\nNew Line 2" ($)Text is a variable of type String
Overwrite ($)Overwrite, with value true ($)Overwrite is a variable of type Boolean
Encoding ($)Encoding, with value null ($)Encoding is a variable of type Encoding

Result

Overwriting "C:\Source\File.txt" with "New Line 1\r\nNew Line 2" results in the content being updated to the following:

New Line 1
New Line 2

Properties

File Path

The File Path to write the Text to.

The File Path is case-insensitive, cannot contain any wildcard characters, and any trailing spaces will be automatically removed.

If the file does not exist at the File Path, a new file is created, and any non-existing folders will also be created.

If the file already exists at the File Path and Overwrite is:

  • true, the Text overwrites the existing file content.
  • false, the Text is appended to the existing file content.

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, please see File & Folder Paths.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)FilePath with no value

Text

The Text to write to the file.

Text can be null or empty (i.e. "").

If Text is null or empty (i.e. "") and Overwrite is:

  • true, a blank file will be written.
  • false, nothing is written.
Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Overwrite

Option to Overwrite the file content with the Text, rather than appending it.

By default, this is set to false to avoid implicit and accidental overwriting of the file content.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value false

Encoding

Option to specify the Encoding that should be used to write the file.

If the Encoding is left as null, the Text will be written using UTF-8 encoding without a byte order mark.

For information about encoding, examples of available encodings and using them, please see Encoding.

Data Type Encoding
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Encoding is invalid (e.g. Encoding.GetEncoding(-1)). See Value Is Invalid.
OperationFailedException The File Path points to a folder.
The File Path contains leading spaces.
The File Path contains only whitespace, or the NUL character (i.e. \0), or contains one or more invalid characters (i.e. ", *, ?, |, <, >, :, \, /) in any file or folder names.
The File Path exceeds the system-defined maximum length (typically 32,767 characters).
The File Path is invalid (for example, it is on an unmapped drive).
The file at the specified File Path is hidden or is a System file, and overwrite is true.
The file at the specified File Path is a read-only file.
The user the flow is executing as does not have the required permissions to write to the file.
An unexpected error occurs when writing the file.
PropertyEmptyException Thrown when File Path is empty (i.e. "").
PropertyNullException Thrown when File Path is null.

Remarks

File Paths

For information about the supported file path formats (i.e. absolute, relative, UNC etc.) and examples of each, including how it is determined if a path points to a folder or a file, please see File & Folder Paths.

File Path needs escaping

File Path requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Source\\File.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Source\File.txt").

Encoding of text

For information about encoding of text, examples of available encodings and using them, please see Encoding.

6.3.8 - Flows

Blocks related to executing Flows.

6.3.8.1 - End Flow

Blocks that indicate the end of a flow.

6.3.8.1.1 - End Flow

Indicates the end of a flow.
Icon

End Flow

(Cortex.Blocks.Flows.EndFlow.EndFlowBlock)

Description

Indicates the end of a flow; when a flow execution reaches this block, the execution is ended.

A flow can contain any number of these blocks, and they can be placed anywhere in a flow.

The block has no block specific properties, but it does have the Description property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block.

A breakpoint can be added to this block when debugging.

Examples

No examples for the block.

Properties

No properties for the block, other than the Description property that is common to all blocks.

Exceptions

No exceptions are thrown by the block.

Remarks

No remarks for the block.

6.3.8.2 - Run Flow

Blocks that are used to run another flow.

6.3.8.2.1 - Run Flow

Runs a chosen Flow, returning any output variables.
Icon

Run Flow

(Cortex.Blocks.Flows.RunFlow.RunFlowBlock)

Description

Runs a chosen Flow using the Inputs provided, returning any Output Variables from the Flow in the Outputs variable.

Examples

Running a Flow

This example will run the Flow square-number-flow saving the output variables to ($)Outputs.

The Flow square-number-flow takes an Input Variable ($)NumberToSquare, which is then multiplied by itself and saved to the Output Variable ($)SquaredNumber. If no value is given for ($)NumberToSquare the default value 10 is used. The flow contains a block that checks that the Input Variable ($)NumberToSquare is larger than 0, an exception is thrown by square-number-flow if ($)NumberToSquare is not larger than 0.

Properties

Property Value Notes
Flow Flow, with value square-number-flow Flow is of type FlowReference
Inputs Inputs is of type InputVariables
    > NumberToSquare ($)NumberToSquare, with value 5 ($)NumberToSquare is of type Int32
Outputs ($)Outputs, with no value ($)Outputs is a variable of type Structure

Result

5 is passed into the Input Variable ($)NumberToSquare for the Flow square-number-flow, which results in 25 being saved to the Output Variable ($)SquaredNumber. This results in the variable ($)Outputs being updated to the following:

{
    "SquaredNumber": 25
}

Running a Flow with Default Input Variables

This example will run the Flow square-number-flow saving the output variables to ($)Outputs.

The Flow square-number-flow takes an Input Variable ($)NumberToSquare, which is then multiplied by itself and saved to the Output Variable ($)SquaredNumber. If no value is given for ($)NumberToSquare the default value 10 is used. The flow contains a block that checks that the Input Variable ($)NumberToSquare is larger than 0, an exception is thrown by square-number-flow if ($)NumberToSquare is not larger than 0.

Properties

Property Value Notes
Flow Flow, with value square-number-flow Flow is of type FlowReference
Inputs Inputs is of type InputVariables
    > NumberToSquare No value (defaults to 10) NumberToSquare is of type Int32
Outputs ($)Outputs, with no value ($)Outputs is a variable of type Structure

Result

As no value is passed into the Input Variable ($)NumberToSquare for the Flow square-number-flow the default of 10 is used, which results in 100 being saved to the Output Variable ($)SquaredNumber. This results in the variable ($)Outputs being updated to the following:

{
    "SquaredNumber": 100
}

For more information see Default Values.


Running a Flow that Throws an Exception

This example will run the Flow square-number-flow saving the output variables to ($)Outputs.

The Flow square-number-flow takes an Input Variable ($)NumberToSquare, which is then multiplied by itself and saved to the Output Variable ($)SquaredNumber. If no value is given for ($)NumberToSquare the default value 10 is used. The flow contains a block that checks that the Input Variable ($)NumberToSquare is larger than 0, an exception is thrown by square-number-flow if ($)NumberToSquare is not larger than 0.

Properties

Property Value Notes
Flow Flow, with value square-number-flow Flow is of type FlowReference
Inputs Inputs is of type InputVariables
    > NumberToSquare ($)NumberToSquare, with value -1 ($)NumberToSquare is of type Int32
Outputs ($)Outputs, with no value ($)Outputs is a variable of type Structure

Result

The Flow square-number-flow contains a block that checks that the Input Variable ($)NumberToSquare is larger than 0; if this is not the case an exception is thrown.

In this example, as -1 is passed into the Input Variable ($)NumberToSquare and is not greater than 0, ($)Outputs is not updated and an exception is thrown. For more information on how the exception is thrown and how to handle the exception see Exceptions Thrown by a Child Flow.


Properties

Flow

The Flow that will be run.

The Literal Editor is the only editor available for this property, and it provides the developer a list of all available flows to choose from.

Data Type FlowReference
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to null)

Inputs

The Input Variables that are passed to the Flow that will be run.

It is recommended to use the Literal Editor for this property as it detects and warns of changes to the Flow Contract, allowing users to Sync the Editor.

Data Type InputVariables
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No initial value (Will be synced when the Flow is first selected)

Outputs

The Output Variables from the Flow.

Each of the Output Variables will be saved to a Structure, where the key is the name of the variable and the item is the value of the variable.

Data Type Structure
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Outputs with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidInputVariablesException Thrown when Inputs is missing any Input Variables from the chosen Flow. See Missing Input Variables.
Thrown when Inputs has any extra Input Variables that are not in the chosen Flow. See Extra Input Variables.
Thrown when Inputs has any Input Variables that are not a valid type for Input Variable. See Input Variables of an Invalid Type.

Remarks

Selecting a Flow

Selecting a Flow Example

A flow can be selected using the Literal Editor on the Flow Property, a list of all available flows will be presented to the developer and can be searched by the Name or Id of a flow.

When a Flow is selected the Inputs Property will be Synced with the Flow Contract.

Default Values

If an Input Variable has a default value, then this default value will be used when running the Flow if the corresponding value in the Inputs Property is left empty. See Running a Flow with Default Input Variables for an example.

Also, if an Input Variable has a default value, and the corresponding value in the Inputs Property is not of the same type, a Validation Error will be raised when the flow is validated.

For more information see Input Variables.

Exceptions Thrown by a Child Flow

If the Flow run by the Run Flow block throws an exception that is unhandled then it is rethrown by the Run Flow block. This can then be handled by any connected Handle Block Exception blocks. See Running a Flow that Throws an Exception for an example.

If an exception thrown by a block is not handled by any connected Handle Block Exception blocks, it will be passed to the Handle Workspace Exception block on the same workspace.

This process repeats until:

For more information see Handling Exceptions.

Syncing the Inputs Property with the Flow Contract

Updating the Flow Contract Example

When a flow is first selected the Inputs Property will be synced with the Flow Contract.

When the contract of the flow changes (e.g. Input Variables of a called Flow are updated), a prompt will appear when the block is selected, allowing the user to sync the editor.

This will cause:

Undoing this action will cause the Inputs Property to return to its previous state, from before it was synced, allowing any data to be retrieved from any extra Input Variables.

Known Limitations

The Flow Property can only use the Literal Editor

The Literal Editor is the only editor available for the Flow Property

In future this limitation may be removed.

Syncing the Inputs Property with the Flow Contract is not available when using editors other than the Literal Editor

Syncing the Inputs Property with the Flow Contract is only available when the Inputs Property uses the Literal Editor. If any other editor is used, the prompt to sync will not be displayed and any changes will need to be resolved manually.

6.3.8.3 - Start Flow

Blocks that indicate the start of a flow.

6.3.8.3.1 - Start Flow

Indicates the start of a flow.
Icon

Start Flow

(Cortex.Blocks.Flows.StartFlow.StartFlowBlock)

Description

Indicates the start of a flow.

This is always the first block in a flow. It cannot be deleted, and a flow can only contain one of these blocks.

The block has no block specific properties, but it does have the Description property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block.

A breakpoint can be added to this block when debugging.

Examples

No examples for the block.

Properties

No properties for the block, other than the Description property that is common to all blocks.

Exceptions

No exceptions are thrown by the block.

Remarks

No remarks for the block.

6.3.9 - Google Workspace

Blocks related to working with Google Workspace.

6.3.9.1 - Gmail

Blocks related to working with Gmail.

6.3.9.1.1 - Send Email

Blocks related to sending Emails.

6.3.9.1.1.1 - Send Email Using Gmail

Sends an email using the SMTP server hosted by Gmail.
Icon

Send Email Using Gmail

(Cortex.Blocks.GoogleWorkspace.Gmail.SendEmail.SendEmailUsingGmailBlock)

Description

Connects to the SMTP server hosted by Gmail using the specified Gmail Session Details, and sends an Email Message.

Close Session can be specified to choose whether the connection to the SMTP server hosted by Gmail is closed or is kept open for use on subsequent Send Email Using Gmail blocks.

Examples

Sending emails using a username and password is not recommended and is being phased out by Gmail. Using a username and password will currently only work for Gmail accounts associated with a Google Workspace that has access enabled for less secure apps. Instead, it is recommended to use an app password or OAuth, for more information, see Less Secure Apps.

In the following examples, where a UserCredentials is used in the Gmail Session Details, the Password property can be either the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password.

For more information, see Setting Credentials.

Sending an email to a single recipient

This example will send an email from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be to set to true within the Gmail Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email to multiple recipients

This example will send an email from sender@gmail.com to recipient1@outlook.com, recipient2@outlook.com and recipient3@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient1@outlook.com"}, {"Name": null, "Address": "recipient2@outlook.com"}, {"Name": null, "Address": "recipient3@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient1@outlook.com"), new EmailAddress("recipient2@outlook.com"), new EmailAddress("recipient3@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient1@outlook.com, recipient2@outlook.com and recipient3@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with a CC or BCC recipient

This example will send an email from sender@gmail.com to recipient@outlook.com with cc@outlook.com and bcc@outlook.com as the CC and BCC recipients for the email respectively. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List<EmailAddress>(){ new EmailAddress("cc@outlook.com") }, bcc: new List<EmailAddress>(){ new EmailAddress("bcc@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body". Both cc@outlook.com and bcc@outlook.com will also recieve copies of the email as they are listed as CC and BCC recipients, and then the session is closed.


Sending an email with multiple CC or BCC recipients

This example will send an email from sender@gmail.com to recipient@outlook.com with cc1@outlook.com and cc2@outlook.com as the CC recipients and bcc1@outlook.com and bcc2@outlook.com as the BCC recipients for the email. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [{"Name": null, "Address": "cc1@outlook.com"}, {"Name": null, "Address": "cc2@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc1@outlook.com"}, {"Name": null, "Address": "bcc2@outlook.com"}], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: new List<EmailAddress>(){ new EmailAddress("cc1@outlook.com"), new EmailAddress("cc2@outlook.com") }, bcc: new List<EmailAddress>(){ new EmailAddress("bcc1@outlook.com"), new EmailAddress("bcc2@outlook.com") }, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body". Both cc1@outlook.com and cc2@outlook.com will also recieve copies of the email as they are listed as CC recipients, and both bcc1@outlook.com and bcc2@outlook.com will recieve copies of the email as they are listed as BCC recipients. Finally, the session is closed.


Sending an email with a different priority

This example will send an email with Urgent priority from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As BodyFormat is null, the email will be sent with a Text body.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Urgent priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with an HTML body

This example will send an email with an HTML body from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Html", "Body": "<h1>Example email body</h1>", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Html, body: "<h1>Example email body</h1>", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority is null, the email will be sent with Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and an HTML body of "<h1>Example email body</h1>", and then the session is closed.


Sending an email with a single attachment

This example will send an email with a single attachment, attachment.txt, from sender@gmail.com to recipient@outlook.com. The attachment is located at C:\attachment.txt on the server executing the flow. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List<string>(){ @"C:\attachment.txt" })
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.

The Attachments are added to the email by providing file paths pointing to the files to be attached to the email.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority containing a text file attachment, attachment.txt, is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with multiple attachments

This example will send an email with mutiple attachments, attachment1.txt and attachment2.txt from sender@gmail.com to recipient@outlook.com. The attachments are located at the paths C:\attachment1.txt and C:\attachment2.txt on the server executing the flow. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be set to true within the Gmail Session Details.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": ["C:\\attachment1.txt", "C:\\attachment2.txt"]}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: new List<string>(){ @"C:\attachment1.txt", @"C:\attachment2.txt" })
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.

The Attachments are added to the email by providing file paths pointing to the files to be attached to the email.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority containing two text file attachments, attachment1.txt and attachment2.txt, is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email with UseSsl set to false

This example will send an email from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 587 which requires UseSsl to be set to false within the Gmail Session Details.

For more information on when UseSsl should be set to true or false, see Setting UseSsl.

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 587, "UseSsl": false}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 587, false), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting Credentials.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Sending an email using OAuth

This example will send an email from sender@gmail.com to recipient@outlook.com. The example uses the SMTP server hosted at smtp.gmail.com on Port 465 which requires UseSsl to be to set to true within the Gmail Session Details.

For more information about when UseSsl should be set to true or false, see Setting UseSsl.

The authentication mechanism used in this example is OAuth, the specific authentication flow used is often referred to as “Two-Legged OAuth”. Therefore, for this example to work correctly:

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@gmail.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@gmail.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Gmail Session Details ($)GmailSessionDetails with value {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}}

In this example ($)GmailSessionDetails has been set up using the following Expression:

new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new GmailOAuthCertificateCredentials(@"C:\certificate.p12", "encryptedPassword", "sender@gmail.com", "clientId"))
($)GmailSessionDetails is a variable of type GmailSessionDetails

The CertificatePath in the GmailOAuthCertificateCredentials is a path pointing to a certificate accessible from the server executing the flow.

For information on:The CertificatePassword property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean

Result

An email with Normal priority is sent from sender@gmail.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the session is closed.


Properties

Email Message

The Email Message to send via the SMTP server hosted by Gmail specified in the Gmail Session Details. This property contains all of the information in relation to the email to be sent, these are:

Note that if the properties Priority and BodyFormat are set to null when creating an EmailMessage using a constructor, the email will be sent with Normal priority and with a Text body.

For more detailed information on each of the properties, see EmailMessage.

Data Type EmailMessage
Property Type Input
Is Advanced false
Default Editor Literal
Default Value EmailMessage with value shown below:
{
  "To": [
    {
      "Name": null,
      "Address": ""
    }
  ],
  "From": {
    "Name": "",
    "Address": ""
  },
  "Cc": [],
  "Bcc": [],
  "Priority": "EmailMessagePriority.Normal",
  "Subject": "",
  "BodyFormat": "EmailMessageBodyFormat.Text",
  "Body": "",
  "Attachments": []
}

Gmail Session Details

The Gmail Session Details object that includes all of the information required to open and maintain a session with an SMTP server hosted by Gmail, including:

If the Close Session property is set to false, then the session will be kept open and can be used in subsequent Send Email Using Gmail blocks which improves performance, see Opening Sessions for more information.

For more detailed information on each of the properties, see GmailSessionDetails.

Data Type GmailSessionDetails
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)GmailSessionDetails with no value

Close Session

Close Session can be specified to choose whether the session is closed or is kept open for use on subsequent Send Email Using Gmail blocks, this defaults to false if left blank, please see Closing Sessions for more information.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when BodyFormat within the Email Message is not one of the specified EmailMessageBodyFormat values (e.g. (EmailMessageBodyFormat)10).
Thrown when Priority within the Email Message is not one of the specified EmailMessagePriority values (e.g. (EmailMessagePriority)10).
Thrown when a file path provided in the Attachments within the Email Message is empty (i.e. ""), contains only whitespace (i.e. " ") or contains the NUL character (i.e. \0).
ArgumentNullException Thrown when a file path provided in the Attachments within the Email Message is null.
EmailSessionException Thrown when an invalid Port is provided in the ServerDetails within the Gmail Session Details. For more information, see Invalid Port.
Thrown when an invalid Host is provided in the ServerDetails within the Gmail Session Details. For more information, see Invalid Host.
Thrown when a connection cannot be established; this typically occurs when UseSsl within Gmail Session Details is set to false with a Port which requires it to be set to true. For more information, see SSL Required.
Thrown when a connection cannot be established; this typically occurs when UseSsl within Gmail Session Details is set to true with a Port which requires it to be set to false. For more information, see SSL Unsupported.
Thrown when the TLS/SSL certificate has expired on the Host or is untrusted or invalid. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when a locally installed anti-virus software replaces the TLS/SSL certificate in order to scan web traffic. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when the CRL (Certificate Revocation List) server for the TLS/SSL certificate is down. For more information, see SSL Unsupported. Note that this exception has the same category and error code as the above row, this is a known limitation, see EmailSessionErrorCode Limitations.
Thrown when the Username and Password in the UserCredentials within Gmail Session Details is incorrect. For more information, see Invalid User Credentials.
Thrown when an invalid CertificatePath and CertificatePassword combination has been provided in the GmailOAuthCertificateCredentials. For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath in the GmailOAuthCertificateCredentials points to an invalid SSL certificate. For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials points to a non-existent file. For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials points to a folder. For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials is longer than the system defined maximum length (typically 32,767). For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials contains only whitespace (i.e. " ") or contains the NUL character (i.e. \0). For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials contains leading spaces. For more information, see Invalid SSL Certificate.
Thrown when the CertificatePath provided in the GmailOAuthCertificateCredentials contains invalid characters (i.e. ", *, ?, |, <, >, :, \, /). For more information, see Invalid SSL Certificate.
Thrown when access is denied to the file at the CertificatePath provided in the GmailOAuthCertificateCredentials. For more information, see Invalid SSL Certificate.
Thrown when an invalid FromAddress and ClientId combination has been provided in the GmailOAuthCertificateCredentials. For more information, see Invalid Gmail Client Credentials.
FileNotFoundException Thrown when a non-existent file path is provided in Attachments within Email Message.
IOException Thrown when the desired socket is held by another process; re-running the flow typically solves this.
Thrown when a file path within Attachments within the Email Message contains leading spaces.
Thrown when a file path within Attachments within the Email Message contains invalid characters (i.e. ", *, ?, |, <, >, :, \, /).
PathTooLongException Thrown when a file path provided in the Attachments within the Email Message exceeds the system-defined maximum length (typically 32,767).
PropertyNullException Thrown when the Gmail Session Details is null.
Thrown when the UserCredentials within Gmail Session Details is null.
Thrown when the ServerDetails within Gmail Session Details is null.
Thrown when the Host in ServerDetails within Gmail Session Details is null.
Thrown when the Email Message is null.
Thrown when the To within Email Message is null.
Thrown when the From within Email Message is null.
Thrown when the Address in an EmailAddress within Email Message is null.
Thrown when the CertificatePath in the GmailOAuthCertificateCredentials within Gmail Session Details is null.
Thrown when the CertificatePassword in the GmailOAuthCertificateCredentials within Gmail Session Details is null.
Thrown when the FromAddress in the GmailOAuthCertificateCredentials within Gmail Session Details is null.
Thrown when the ClientId in the GmailOAuthCertificateCredentials within Gmail Session Details is null.
PropertyEmptyException Thrown when the Host in ServerDetails within Gmail Session Details is empty (i.e. "").
Thrown when the To within Email Message is empty (i.e. []).
Thrown when the Address in an EmailAddress within Email Message is empty (i.e. "").
Thrown when the CertificatePath in the GmailOAuthCertificateCredentials within Gmail Session Details is empty (i.e. "").
Thrown when the CertificatePassword in the GmailOAuthCertificateCredentials within Gmail Session Details is empty (i.e. "").
Thrown when the FromAddress in the GmailOAuthCertificateCredentials within Gmail Session Details is empty (i.e. "").
Thrown when the ClientId in the GmailOAuthCertificateCredentials within Gmail Session Details is empty (i.e. "").
PropertyValueOutOfRangeException Thrown when the Port in the ServerDetails within Gmail Session Details is below 1 or above 65535. For more information, see Property Is Invalid.
SmtpCommandException Thrown when the Address in an EmailAddress within Email Message is not of the correct format (RFC 5321).
Thrown when the combined size of all of the attachments in the list of Attachments within the Email Message is greater than the limit specified by the email service provider; for Gmail this is 25 MB.
UnauthorizedAccessException Thrown when access is denied to a file provided in Attachments within Email Message.
Thrown when a file path within the Attachments property within Email Message points to a folder.

Remarks

How does Priority affect sending an email?

An email sent with Urgent or NonUrgent priority will have its priority displayed differently depending on the email client. For example, Outlook displays an email that has an Urgent priority with a red exclamation mark like so:

Important email

For more information on how the priority of an email will be displayed, see the help provided by the respective email client.

How does BodyFormat affect sending an email?

An email sent with an HTML body will have its body displayed as an HTML page instead of as plain text. How the email looks in the email client may differ depending on the email client in use. For example, if the Email Message has its BodyFormat set to HTML and the Body has a value of:

"<h1>Example header text</h1><p>Example paragraph text</p>"

Outlook will display the email body as follows:

HTML email

For more information on how the body of an email will be displayed, see the help provided by the respective email client.

Attachments

Attachments can be sent in an email by providing a list of file paths in the Attachments property of the Email Message. For more information concerning attaching files to an email, see the sections below.

Supported file path formats

Each file path in the Attachments within the Email Message can be an:

  • Absolute file path
  • Relative file path
  • UNC file path

where each file path must be accessible from the server executing the flow.

For more information about each of these supported file path formats, please see File & Folder Paths.

File paths need escaping

Each file path in the Attachments within the Email Message requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Attachments\\attachment.txt"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Attachments\attachment.txt")

Null file path

If null is provided as a file path in the Attachments within the Email Message, an ArgumentNullException is thrown.

Empty file path

If an empty string is provided as a file path in the the Attachments within the Email Message, an ArgumentException is thrown.

File path does not exist

If a file path in the Attachments within the Email Message does not exist, a FileNotFoundException is thrown.

Invalid file path

If a file path in the Attachments within the Email Message is invalid (i.e. contains any of the following characters: “, *, ?, |, <, >, :, , /), an IOException will be thrown.

File path points to a folder

If a file path in the Attachments within the Email Message points to a folder, an UnauthorizedAccessException will be thrown.

File path contains leading spaces

If a file path in the Attachments within the Email Message contains leading spaces they are not removed and an IOException will be thrown; however, trailing spaces are removed.

File path contains only whitespace or the NUL character

If a file path in the Attachments within the Email Message contains only whitespace (i.e. " ") or the NUL character (i.e. \0), an ArgumentException will be thrown.

File path exceeds the system-defined maximum length

If a file path in the Attachments within the Email Message exceeds the system-defined maximum length (typically 32,767), a PathTooLongException will be thrown.

User does not have necessary permissions to attach the file

If the user the flow is executing as does not have permissions to access the file at the provided file path in the Attachments within the Email Message, an UnauthorizedAccessException will be thrown.

Attachment size limit

The combined size of all the Attachments within the Email Message must be less than the limit specified by the email service provider. If the combined size of all of the attachments is greater than the limit, an SmtpCommandException will be thrown.

For Outlook this is 20 MB and for Gmail this is 25 MB, for more information on the size limits for other email service providers, see the help provided by the respective email service provider.

Supported formats for ServerDetails.Host

The following formats are supported for Host in ServerDetails:

  • Fully Qualified Domain Name (e.g. "smtp.gmail.com")

Setting UseSsl

The ServerDetails within the Gmail Session Details specifies which SMTP server to connect to. The value of the UseSsl property inside this object depends on the Host and Port being connected to. There are two types of SSL/TLS connections that can occur:

  • SSL/TLS is used as soon as a connection is established
  • SSL/TLS is used via the STARTTLS command if it is available

The above two points correspond to the UseSsl property being set to true and false respectively. As such, generally the following rules can be followed to determine whether UseSsl should be set to true or false:

  • If the Port being connected to is 465 then UseSsl should be set to true
  • If the Port being connected to is 25 or 587 then UseSsl should be set to false

Setting Credentials

The Credentials within the Gmail Session Details specifies what user to connect as on the SMTP server hosted by Gmail. Two types of authentication are supported:

  • Basic
  • OAuth (Two-Legged OAuth)

The above two authentication mechanisms correspond to the Credentials within the Gmail Session Details being a UserCredentials and a GmailOAuthCertificateCredentials respectively.

Setting Credentials to UserCredentials

Currently, Gmail will not allow emails to be sent using the username and password of an account unless the account is associated with a Google Workspace account.

As such, the recommended approach for using a UserCredentials as the Credentials within the Gmail Session Details is to set up an app password and use that in place of the actual password associated with the account, see Setting up an app password for a Gmail account for more information.

Note the following:

Setting Credentials to GmailOAuthCertificateCredentials

In order to use OAuth as the authentication mechanism:

  • A client application must be set up on the Google Workspace
  • A service account must be set up for the client application
  • A private key (.p12 file) must be generated for the service account
  • An administrator of the Google Workspace must grant the client application domain-wide delegation for the scope https://mail.google.com/

For more information on how to configure a Gmail account to work with OAuth, see Setting up a Gmail account for OAuth authentication.

Once the account has been set up to work with OAuth, a GmailOAuthCertificateCredentials can be used as the Credentials within the Gmail Session Details. The properties in the GmailOAuthCertificateCredentials correspond with the client application data as follows:

  • CertificatePath - The path pointing to the certificate (.p12) file generated when setting up the client application; the certificate must be accessible from the server executing the flow, for more information on using a certificate file, see Certificate Files.
  • CertificatePassword - The password associated with the certificate (.p12)
  • FromAddress - The address of the account used to set up the client application
  • ClientId - The Client ID of the client application

Note that the values of the CertificatePath and ClientId properties may optionally be encrypted, however the CertificatePassword must be encrypted otherwise an UnencryptedTextException will be thrown when the object is created

For more detailed information on each of these properties, see GmailOAuthCertificateCredentials.

Certificate Files

OAuth can be used as the authentication mechanism when sending an email using this block by providing a GmailOAuthCertificateCredentials as the Credentials in the Gmail Session Details. GmailOAuthCertificateCredentials requires a CertificatePath to be provided, which is a path pointing to a certificate file accessible from the server executing the flow. For more information concerning using a certificate, see the sections below.

Supported CertificatePath formats

The CertificatePath within the GmailOAuthCertificateCredentials can be an:

  • Absolute file path
  • Relative file path
  • UNC file path

where each file path must be accessible from the server executing the flow.

For more information about each of these supported file path formats, please see File & Folder Paths.

CertificatePath needs escaping

The CertificatePath within the GmailOAuthCertificateCredentials requires \ characters to be escaped, otherwise each unescaped \ will be reported as an Invalid property value message when trying to debug the flow.

Escaping can be done in two ways:

  • Escaping the \ character with another \ character (e.g. "C:\\Certificates\\certificate.p12"), or
  • Prepending an @ character before the start of the File Path (e.g. @"C:\Certificates\certificate.p12")

Null CertificatePath

If null is provided as the CertificatePath within the GmailOAuthCertificateCredentials, a PropertyNullException is thrown.

Empty CertificatePath

If an empty string is provided as the CertificatePath within the GmailOAuthCertificateCredentials, a PropertyEmptyException is thrown.

CertificatePath does not exist

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials does not exist, an EmailSessionException is thrown. For more information, see Invalid SSL Certificate.

Invalid CertificatePath

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials is invalid (i.e. contains any of the following characters: “, *, ?, |, <, >, :, , /), an EmailSessionException will be thrown. For more information, see Invalid SSL Certificate.

CertificatePath points to a folder

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials points to a folder, an EmailSessionException will be thrown. For more information, see Invalid SSL Certificate.

CertificatePath contains leading spaces

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials contains leading spaces they are not removed and an EmailSessionException will be thrown; however, trailing spaces are removed. For more information, see Invalid SSL Certificate.

CertificatePath contains only whitespace or the NUL character

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials contains only whitespace (i.e. " ") or the NUL character (i.e. \0), an EmailSessionException will be thrown. For more information, see Invalid SSL Certificate.

CertificatePath exceeds the system-defined maximum length

If the path provided as the CertificatePath within the GmailOAuthCertificateCredentials exceeds the system-defined maximum length (typically 32,767), an EmailSessionException will be thrown. For more information, see Invalid SSL Certificate.

User does not have necessary permissions to use the certificate file

If the user the flow is executing as does not have permissions to access the file at the CertificatePath within the GmailOAuthCertificateCredentials, an EmailSessionException will be thrown. For more information, see Invalid SSL Certificate.

Opening Sessions

The Send Email Using Gmail block automatically handles creating and opening sessions for the specified Gmail Session Details using the following rules:

  • If a session does not exist, a new session will be created, opened and used when the block runs.
  • If a session already exists but is closed, the session will be opened and used when the block runs.
  • If a session already exists and is open, the session will be used when the block runs.

Gmail Session Details will keep the session open across multiple Send Email Using Gmail blocks as long as Close Session is set to false. Keeping the session open helps increase the performance of the block due to the subsequent blocks not having to spend resources creating and opening sessions for each execution.

Note that for all SSL connections, the protocol to be used will be negotiated with the server depending on which protocols are available. Similarly, the SASL mechanism to be used will be negotiated with the mail server based on the available mechanisms.

For information on how to explicitly close a session, please see Closing Sessions.

Closing Sessions

Sessions can be explicitly closed by setting Close Session to true. This causes the session to be closed after the Email Message has been sent.

If Close Session is set to false the session will be closed when the Variable that Gmail Session Details is set to goes out of scope or the flow ends, whichever happens first. For more information about variables and scope, please see Variables.

For information on how to open a session, please see Opening Sessions.

Known Limitations

None

6.3.10 - Http

Blocks related to working with HTTP.

6.3.10.1 - Execute Http Request

Blocks related to executing HTTP requests.

6.3.10.1.1 - Execute Http Request

Executes an HTTP request and returns a response.
Icon

Execute Http Request

(Cortex.Blocks.Http.ExecuteHttpRequest.ExecuteHttpRequestBlock`1)

Description

Executes an HTTP Request using the specified Http Credentials and returns the Http Response.

Examples

The following examples will use an example API with a base Uri of https://test-shop.com/api and resource called items at https://test-shop.com/api/items. Each example assumes that the resource items contains the following data before the example is executed:

[
    {
        "name": "item 1",
        "id": 1
    },
    {
        "name": "item 2",
        "id": 2
    }
]

The example API supports:

  • Retrieval of every item in the items resource via a GET request which returns the items resource as the ResponseBody of the Http Response
  • Creation of a new item in the items resource via a POST request which returns the updated items resource as the ResponseBody of the Http Response
  • Unauthenticated requests
  • Basic authentication
  • Retrieval of access tokens from https://test-shop.com/api/oauth2/token
  • OAuth authentication using password credentials
  • OAuth authentication using client credentials

Executing a GET request

This example will send a GET request to https://test-shop.com/api/items using HTTP 1.1 with no authentication which requires Http Credentials to be null.

Note that the result of executing an Http Request is dependent on the API that the request is being made to.

Properties

Property Value Notes
Http Request ($)HttpRequest, with value {"QueryStringParameters": null, "Verb": "RequestVerb.GET", "ContentType": null, "Body": null, "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)HttpRequest has been set up using the following Expression:

new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)
($)HttpRequest is a variable of type HttpRequest
Http Credentials ($)HttpCredentials, with value null

In this example, ($)HttpCredentials has been set up using the following Expression:

null
($)HttpCredentials is a variable with value null

As ($)HttpCredentials is null, no authentication will occur when making the request.
Http Response ($)HttpResponse, with no value ($)HttpResponse will be set to the type HttpResponse

Result

Executing an HttpRequest with a Uri of https://test-shop.com/api/items and a Verb of GET using HTTP 1.1 results in the variable ($)HttpResponse being updated to the following:

{
    "ResponseBody": [
        {
            "name": "item 1",
            "id": 1
        },
        {
            "name": "item 2",
            "id": 2
        }
    ],
    "ErrorMessage": null,
    "Headers": {
        "Content-Length": 1024,
        "Content-Type": "application/json",
    },
    "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of application/json, the ResponseBody is a Structure containing the data.


Executing a POST request

This example will send a POST request to https://test-shop.com/api/items using HTTP 1.1 with no authentication which requires Http Credentials to be null.

Note that the result of executing an Http Request is dependent on the API that the request is being made to.

Properties

Property Value Notes
Http Request ($)HttpRequest, with value {"QueryStringParameters": null, "Verb": "RequestVerb.POST", "ContentType": "application/json", "Body": "{'name': 'item 3', 'id': 3}", "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)HttpRequest has been set up using the following Expression:

new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.POST, contentType: "application/json", headers: null, body: "{'name': 'item 3', 'id': 3}", httpVersion: HttpRequestVersion.HTTP11)
($)HttpRequest is a variable of type HttpRequest
Http Credentials ($)HttpCredentials, with value null

In this example, ($)HttpCredentials has been set up using the following Expression:

null
($)HttpCredentials is a variable with value null

As ($)HttpCredentials is null, no authentication will occur when making the request.
Http Response ($)HttpResponse, with no value ($)HttpResponse will be set to the type HttpResponse

Result

Executing an HttpRequest with a Uri of https://test-shop.com/api/items and a Verb of POST using HTTP 1.1 results in the variable ($)HttpResponse being updated to the following:

{
    "ResponseBody": [
        {
            "name": "item 1",
            "id": 1
        },
        {
            "name": "item 2",
            "id": 2
        },
        {
            "name": "item 3",
            "id": 3
        }
    ],
    "ErrorMessage": null,
    "Headers": {
        "Content-Length": 1024,
        "Content-Type": "application/json",
    },
    "StatusCode": "HttpStatusCode.OK (200)"
}

Note the following:

  • The resource items at https://test-shop.com/api/items contains item 3 as shown in the ResponseBody of the Http Response shown above
  • As the Headers contains a key of Content-Type with a value of application/json, the ResponseBody is a Structure containing the data

Executing a request using Basic authentication

This example will send a GET request to https://test-shop.com/api/items using HTTP 1.1 using Basic authentication which requires Http Credentials to be a UserCredentials.

Note that the result of executing an Http Request is dependent on the API that the request is being made to.

Properties

Property Value Notes
Http Request ($)HttpRequest, with value {"QueryStringParameters": null, "Verb": "RequestVerb.GET", "ContentType": null, "Body": null, "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)HttpRequest has been set up using the following Expression:

new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)
($)HttpRequest is a variable of type HttpRequest
Http Credentials ($)HttpCredentials, with value {"Domain": null, "Username": "username", "Password": "encryptedPassword"}

In this example, ($)HttpCredentials has been set up using the following Expression:

new UserCredentials(username: "username", password: "encryptedPassword")
($)HttpCredentials is a variable of type UserCredentials

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Http Response ($)HttpResponse, with no value ($)HttpResponse will be set to the type HttpResponse

Result

Executing an HttpRequest with a Uri of https://test-shop.com/api/items and a Verb of GET using HTTP 1.1 results in the variable ($)HttpResponse being updated to the following:

{
    "ResponseBody": [
        {
            "name": "item 1",
            "id": 1
        },
        {
            "name": "item 2",
            "id": 2
        }
    ],
    "ErrorMessage": null,
    "Headers": {
        "Content-Length": 1024,
        "Content-Type": "application/json",
    },
    "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of application/json, the ResponseBody is a Structure containing the data.


Executing a request using OAuth password credentials

This example will send a GET request to https://test-shop.com/api/items using HTTP 1.1 using OAuth authentication with password credentials which requires Http Credentials to be a HttpOAuthPasswordCredentials.

Note that the result of executing an Http Request is dependent on the API that the request is being made to.

Properties

Property Value Notes
Http Request ($)HttpRequest, with value {"QueryStringParameters": null, "Verb": "RequestVerb.GET", "ContentType": null, "Body": null, "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)HttpRequest has been set up using the following Expression:

new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)
($)HttpRequest is a variable of type HttpRequest
Http Credentials ($)HttpCredentials, with value {"AccessTokenUri": "https://test-shop.com/api/oauth2/token", "ClientAuthentication": null, "Scope": null, "ResourceOwnerUsername": "username", "ResourceOwnerPassword": "encryptedPassword"}

In this example, ($)HttpCredentials has been set up using the following Expression:

new HttpOAuthPasswordCredentials(accessTokenUri: "https://test-shop.com/api/oauth2/token", clientAuthentication: null, scope: null, resourceOwnerUsername: "username", resourceOwnerPassword: "encryptedPassword")
($)HttpCredentials is a variable of type HttpOAuthPasswordCredentials

The ResourceOwnerPassword property in the HttpOAuthPasswordCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Http Response ($)HttpResponse, with no value ($)HttpResponse will be set to the type HttpResponse

Result

Executing an HttpRequest with a Uri of https://test-shop.com/api/items and a Verb of GET using HTTP 1.1 results in the variable ($)HttpResponse being updated to the following:

{
    "ResponseBody": [
        {
            "name": "item 1",
            "id": 1
        },
        {
            "name": "item 2",
            "id": 2
        }
    ],
    "ErrorMessage": null,
    "Headers": {
        "Content-Length": 1024,
        "Content-Type": "application/json",
    },
    "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of application/json, the ResponseBody is a Structure containing the data.


Executing a request using OAuth client credentials

This example will send a GET request to https://test-shop.com/api/items using HTTP 1.1 using OAuth authentication with client credentials which requires Http Credentials to be a HttpOAuthClientCredentials.

Note that the result of executing an Http Request is dependent on the API that the request is being made to.

Properties

Property Value Notes
Http Request ($)HttpRequest, with value {"QueryStringParameters": null, "Verb": "RequestVerb.GET", "ContentType": null, "Body": null, "Uri": "https://test-shop.com/api/items", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)HttpRequest has been set up using the following Expression:

new HttpRequest(uri: "https://test-api/com/items", queryParameters: null, verb: RequestVerb.GET, contentType: null, headers: null, body: null, httpVersion: HttpRequestVersion.HTTP11)
($)HttpRequest is a variable of type HttpRequest
Http Credentials ($)HttpCredentials, with value {"AccessTokenUri": "https://test-shop.com/api/oauth2/token", "ClientAuthentication": {"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "SendAs": "ClientAuthType.Header"}, "Scope": null}

In this example, ($)HttpCredentials has been set up using the following Expression:

new HttpOAuthClientCredentials(accessTokenUri: "https://test-shop.com/api/oauth2/token", clientAuthentication: new ClientAuthentication("clientId", "encryptedClientSecret", ClientAuthType.Header), scope: null)
($)HttpCredentials is a variable of type HttpOAuthClientCredentials

The ClientSecret property in ClientAuthentication must be encrypted, for more information on how to encrypt the ClientSecret, see EncryptedText.
Http Response ($)HttpResponse, with no value ($)HttpResponse will be set to the type HttpResponse

Result

Executing an HttpRequest with a Uri of https://test-shop.com/api/items and a Verb of GET using HTTP 1.1 results in the variable ($)HttpResponse being updated to the following:

{
    "ResponseBody": [
        {
            "name": "item 1",
            "id": 1
        },
        {
            "name": "item 2",
            "id": 2
        }
    ],
    "ErrorMessage": null,
    "Headers": {
        "Content-Length": 1024,
        "Content-Type": "application/json",
    },
    "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of application/json, the ResponseBody is a Structure containing the data.


Properties

Http Request

The Http Request to execute using the Http Credentials. This property contains all of the information in relation to the request to be sent, these are:

For more detailed information on each of the properties, see HttpRequest.

Data Type HttpRequest
Property Type Input
Is Advanced false
Default Editor Literal
Default Value HttpRequest with value shown below:
{
    "Uri": "",
    "QueryParameters": null,
    "Verb": "RequestVerb.GET",
    "ContentType": "application/json",
    "Headers": null,
    "Body": "",
    "HttpVersion": "HttpRequestVersion.HTTP10"
}

Http Credentials

The Http Credentials object that includes all of the information required for authentication. Mutliple authentication mechanisms are supported which correspond to specific values/data types:

Note that when using HttpOAuthPasswordCredentials or HttpOAuthClientCredentials as the Http Credentials, the Execute Http Request block automatically handles retrieval of access tokens using the following rules:

  • If an access token does not exist, a new access token will be retrieved and used when the block runs.
  • If an access token already exists but is expired, a new access token will be retrieved and used when the block runs.
  • If an access token already exists and is valid, it will be used when the block runs.
Data Type HttpCredentials
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)HttpCredentials with no value

Http Response

The Http Response object which contains the response returned from the server. This property contains all of the information in relation to the response from the server, these are:

Note that if the Headers contains a key of Content-Type with a value containing json or xml, the ResponseBody will be set to a Structure containing the data.

For more detailed information on each of the properties, see HttpResponse.

Data Type HttpResponse
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)HttpResponse with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
HttpAuthorisationException Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is invalid.
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is invalid.
Thrown when the ResourceOwnerPassword within HttpOAuthPasswordCredentials is invalid.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is invalid.
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is invalid.
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is invalid.
InvalidRequestException Thrown when the Uri within Http Request is not in the correct format or contains invalid characters.
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is not in the correct format or contains invalid characters.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is not in the correct format or contains invalid characters.
Thrown when the Verb within Http Request is not one of the specified RequestVerb values (e.g. (RequestVerb)10).
Thrown when a header key in Headers within Http Request is empty (i.e. "").
Thrown when a header key in Headers within Http Request is restricted.
Thrown when a header key in Headers within Http Request is restricted and forbidden.
Thrown when a header value in Headers within Http Request could not be assigned to its restricted header key.
Thrown when a header value in Headers within Http Request could not be converted to its restricted header key’s type.
Thrown when the Body within Http Request is not null or empty (i.e. "") and RequestVerb is GET or HEAD.
Thrown when the Body within Http Request does not match the ContentType.
Thrown when the HttpVersion within Http Request is not one of the specified HttpRequestVersion values (e.g. (HttpRequestVersion)20).
PropertyNullException Thrown when the Http Request is null.
Thrown when the Uri within Http Request is null.
Thrown when the Username within UserCredentials is null.
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is null.
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is null.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is null.
Thrown when the ClientAuthentication within HttpOAuthClientCredentials is null.
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is null.
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is null.
PropertyEmptyException Thrown when the Uri within Http Request is empty (i.e. "").
Thrown when the Username within UserCredentials is empty (i.e. "").
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is empty (i.e. "").
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is empty (i.e. "").
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is empty (i.e. "").
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is empty (i.e. "").
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is empty (i.e. "").

Remarks

Known Limitations

None

6.3.10.2 - Execute Soap Request

Blocks related to executing SOAP requests.

6.3.10.2.1 - Execute Soap Request

Executes a SOAP request and returns a response.
Icon

Execute Soap Request

(Cortex.Blocks.Http.ExecuteSoapRequest.ExecuteSoapRequestBlock`1)

Description

Executes a Soap Request using the specified Http Credentials and returns the Soap Response.

Examples

The following examples will use an example SOAP service with a base Uri of https://test-converter.com/xml.

The example SOAP service supports the following:

  • Conversion of a temperature in Degrees Celcius to Kelvin using an Action of https://test-converter.com/DegreesToKelvin
  • Unauthenticated requests
  • Basic authentication
  • Retrieval of access tokens from https://test-converter.com/oauth2/token
  • OAuth authentication using password credentials
  • OAuth authentication using client credentials

Executing a request using SOAP 1.1

This example will send a Soap Request to https://test-converter.com/xml using SOAP 1.1 with no authentication which requires:

Note that the result of executing a Soap Request is dependent on the SOAP service that the request is being made to.

Properties

Property Value Notes
Soap Request ($)SoapRequest, with value {"SoapMessage": {"Action": "https://test-converter.com/DegreesToKelvin", "Envelope": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)SoapRequest has been set up using the following Expression:

new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>"), headers: null, httpVersion: HttpRequestVersion.HTTP11)
($)SoapRequest is a variable of type SoapRequest
Http Credentials ($)HttpCredentials, with value null

In this example, ($)HttpCredentials has been set up using the following Expression:

null
($)HttpCredentials is a variable with value null

As ($)HttpCredentials is null, no authentication will occur when making the request.
Soap Response ($)SoapResponse, with no value ($)SoapResponse will be set to the type SoapResponse

Result

Executing a Soap Request with a Uri of https://test-converter.com/xml using a Soap11Message with an Action of https://test-converter.com/DegreesToKelvin results in the variable ($)SoapResponse being updated to the following:

{
  "ResponseEnvelope": {
    "?xml": {
      "@version": "1.0",
      "@encoding": "utf-8"
    },
    "soap:Envelope": {
      "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
      "soap:Body": {
        "DegreesToKelvinResponse": {
          "@xmlns": "https://test-converter.com/DegreesToKelvin/schema",
          "kelvin": "293"
        }
      }
    }
  },
  "ErrorMessage": null,
  "Headers": {
    "Content-Type": "text/xml; charset=utf-8"
  },
  "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of text/xml; charset=utf-8, the ResponseEnvelope is a Structure containing the data.


Executing a request using SOAP 1.2

This example will send a Soap Request to https://test-converter.com/xml using SOAP 1.2 with no authentication which requires:

Note that the result of executing a Soap Request is dependent on the SOAP service that the request is being made to.

Properties

Property Value Notes
Soap Request ($)SoapRequest, with value {"SoapMessage": {"Envelope": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap12:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap12=\"http://www.w3.org/2003/05/soap-envelope\"><soap12:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap12:Body></soap12:Envelope>", "Version": 12}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)SoapRequest has been set up using the following Expression:

new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap12Message("<?xml version=\"1.0\" encoding=\"utf-8\"?><soap12:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap12=\"http://www.w3.org/2003/05/soap-envelope\"><soap12:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap12:Body></soap12:Envelope>"), headers: null, httpVersion: HttpRequestVersion.HTTP11)
($)SoapRequest is a variable of type SoapRequest
Http Credentials ($)HttpCredentials, with value null

In this example, ($)HttpCredentials has been set up using the following Expression:

null
($)HttpCredentials is a variable with value null

As ($)HttpCredentials is null, no authentication will occur when making the request.
Soap Response ($)SoapResponse, with no value ($)SoapResponse will be set to the type SoapResponse

Result

Executing a Soap Request with a Uri of https://test-converter.com/xml using a Soap12Message results in the variable ($)SoapResponse being updated to the following:

{
  "ResponseEnvelope": {
    "?xml": {
      "@version": "1.0",
      "@encoding": "utf-8"
    },
    "soap12:Envelope": {
      "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "@xmlns:soap12": "http://www.w3.org/2003/05/soap-envelope",
      "soap12:Body": {
        "DegreesToKelvinResponse": {
          "@xmlns": "https://test-converter.com/DegreesToKelvin/schema",
          "kelvin": "293"
        }
      }
    }
  },
  "ErrorMessage": null,
  "Headers": {
    "Content-Type": "application/soap+xml; charset=utf-8"
  },
  "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of application/soap+xml; charset=utf-8, the ResponseEnvelope is a Structure containing the data.


Executing a request using Basic authentication

This example will send a Soap Request to https://test-converter.com/xml using SOAP 1.1 with Basic authentication which requires:

Note that the result of executing a Soap Request is dependent on the SOAP service that the request is being made to.

Properties

Property Value Notes
Soap Request ($)SoapRequest, with value {"SoapMessage": {"Action": "https://test-converter.com/DegreesToKelvin", "Envelope": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)SoapRequest has been set up using the following Expression:

new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>"), headers: null, httpVersion: HttpRequestVersion.HTTP11)
($)SoapRequest is a variable of type SoapRequest
Http Credentials ($)HttpCredentials, with value {"Domain": null, "Username": "username", "Password": "encryptedPassword"}

In this example, ($)HttpCredentials has been set up using the following Expression:

new UserCredentials(username: "username", password: "encryptedPassword")
($)HttpCredentials is a variable of type UserCredentials

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Soap Response ($)SoapResponse, with no value ($)SoapResponse will be set to the type SoapResponse

Result

Executing a Soap Request with a Uri of https://test-converter.com/xml using a Soap11Message with an Action of https://test-converter.com/DegreesToKelvin results in the variable ($)SoapResponse being updated to the following:

{
  "ResponseEnvelope": {
    "?xml": {
      "@version": "1.0",
      "@encoding": "utf-8"
    },
    "soap:Envelope": {
      "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
      "soap:Body": {
        "DegreesToKelvinResponse": {
          "@xmlns": "https://test-converter.com/DegreesToKelvin/schema",
          "kelvin": "293"
        }
      }
    }
  },
  "ErrorMessage": null,
  "Headers": {
    "Content-Type": "text/xml; charset=utf-8"
  },
  "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of text/xml; charset=utf-8, the ResponseEnvelope is a Structure containing the data.


Executing a request using OAuth password credentials

This example will send a Soap Request to https://test-converter.com/xml using SOAP 1.1 with OAuth authentication using password credentials which requires:

Note that the result of executing a Soap Request is dependent on the SOAP service that the request is being made to.

Properties

Property Value Notes
Soap Request ($)SoapRequest, with value {"SoapMessage": {"Action": "https://test-converter.com/DegreesToKelvin", "Envelope": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)SoapRequest has been set up using the following Expression:

new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>"), headers: null, httpVersion: HttpRequestVersion.HTTP11)
($)SoapRequest is a variable of type SoapRequest
Http Credentials ($)HttpCredentials, with value {"AccessTokenUri": "https://test-converter.com/oauth2/token", "ClientAuthentication": null, "Scope": null, "ResourceOwnerUsername": "username", "ResourceOwnerPassword": "encryptedPassword"}

In this example, ($)HttpCredentials has been set up using the following Expression:

new HttpOAuthPasswordCredentials(accessTokenUri: "https://test-converter.com/oauth2/token", clientAuthentication: null, scope: null, resourceOwnerUsername: "username", resourceOwnerPassword: "encryptedPassword")
($)HttpCredentials is a variable of type HttpOAuthPasswordCredentials

The ResourceOwnerPassword property in the HttpOAuthPasswordCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Soap Response ($)SoapResponse, with no value ($)SoapResponse will be set to the type SoapResponse

Result

Executing a Soap Request with a Uri of https://test-converter.com/xml using a Soap11Message with an Action of https://test-converter.com/DegreesToKelvin results in the variable ($)SoapResponse being updated to the following:

{
  "ResponseEnvelope": {
    "?xml": {
      "@version": "1.0",
      "@encoding": "utf-8"
    },
    "soap:Envelope": {
      "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
      "soap:Body": {
        "DegreesToKelvinResponse": {
          "@xmlns": "https://test-converter.com/DegreesToKelvin/schema",
          "kelvin": "293"
        }
      }
    }
  },
  "ErrorMessage": null,
  "Headers": {
    "Content-Type": "text/xml; charset=utf-8"
  },
  "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of text/xml; charset=utf-8, the ResponseEnvelope is a Structure containing the data.


Executing a request using OAuth client credentials

This example will send a Soap Request to https://test-converter.com/xml using SOAP 1.1 with OAuth authentication using client credentials which requires:

Note that the result of executing a Soap Request is dependent on the SOAP service that the request is being made to.

Properties

Property Value Notes
Soap Request ($)SoapRequest, with value {"SoapMessage": {"Action": "https://test-converter.com/DegreesToKelvin", "Envelope": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>", "Version": 11}, "Uri": "https://test-converter.com/xml", "Headers": null, "HttpVersion": "HttpRequestVersion.HTTP11"}

In this example ($)SoapRequest has been set up using the following Expression:

new SoapRequest(uri: "https://test-converter.com/xml", soapMessage: new Soap11Message("https://test-converter.com/DegreesToKelvin", "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><DegreesToKelvin xmlns=\"https://test-converter.com/DegreesToKelvin/schema\"><degrees>20</degrees></DegreesToKelvin></soap:Body></soap:Envelope>"), headers: null, httpVersion: HttpRequestVersion.HTTP11)
($)SoapRequest is a variable of type SoapRequest
Http Credentials ($)HttpCredentials, with value {"AccessTokenUri": "https://test-converter.com/oauth2/token", "ClientAuthentication": {"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "SendAs": "ClientAuthType.Header"}, "Scope": null}

In this example, ($)HttpCredentials has been set up using the following Expression:

new HttpOAuthClientCredentials(accessTokenUri: "https://test-converter.com/oauth2/token", clientAuthentication: new ClientAuthentication("clientId", "encryptedClientSecret", ClientAuthType.Header), scope: null)
($)HttpCredentials is a variable of type HttpOAuthClientCredentials

The ClientSecret property in ClientAuthentication must be encrypted, for more information on how to encrypt the ClientSecret, see EncryptedText.
Soap Response ($)SoapResponse, with no value ($)SoapResponse will be set to the type SoapResponse

Result

Executing a Soap Request with a Uri of https://test-converter.com/xml using a Soap11Message with an Action of https://test-converter.com/DegreesToKelvin results in the variable ($)SoapResponse being updated to the following:

{
  "ResponseEnvelope": {
    "?xml": {
      "@version": "1.0",
      "@encoding": "utf-8"
    },
    "soap:Envelope": {
      "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
      "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
      "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
      "soap:Body": {
        "DegreesToKelvinResponse": {
          "@xmlns": "https://test-converter.com/DegreesToKelvin/schema",
          "kelvin": "293"
        }
      }
    }
  },
  "ErrorMessage": null,
  "Headers": {
    "Content-Type": "text/xml; charset=utf-8"
  },
  "StatusCode": "HttpStatusCode.OK (200)"
}

Note that as the Headers contains a key of Content-Type with a value of text/xml; charset=utf-8, the ResponseEnvelope is a Structure containing the data.


Properties

Soap Request

The Soap Request to execute using the Http Credentials. This property contains all of the information in relation to the request to be sent, these are:

SOAP 1.1 and SOAP 1.2 are both supported, which correspond to SoapMessage within SoapRequest being a Soap11Message and Soap12Message respectively.

For more information on:

Data Type SoapRequest
Property Type Input
Is Advanced false
Default Editor Literal
Default Value SoapRequest with value shown below:
{
    "SoapMessage": {
        "Action": "",
        "Envelope": "",
        "Version": 11
    },
    "Uri": "",
    "Headers": null,
    "HttpVersion": "HttpRequestVersion.HTTP10"
}

Http Credentials

The Http Credentials object that includes all of the information required for authentication. Mutliple authentication mechanisms are supported which correspond to specific values/data types:

Note that when using HttpOAuthPasswordCredentials or HttpOAuthClientCredentials as the Http Credentials, the Execute Soap Request block automatically handles retrieval of access tokens using the following rules:

  • If an access token does not exist, a new access token will be retrieved and used when the block runs.
  • If an access token already exists but is expired, a new access token will be retrieved and used when the block runs.
  • If an access token already exists and is valid, it will be used when the block runs.
Data Type HttpCredentials
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)HttpCredentials with no value

Soap Response

The Soap Response object which contains the response returned from the server. This property contains all of the information in relation to the response from the server, these are:

Note that if the Headers contains a key of Content-Type with a value containing json or xml, the ResponseEnvelope will be set to a Structure containing the data.

For more detailed information on each of the properties, see SoapResponse.

Data Type SoapResponse
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)SoapResponse with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
HttpAuthorisationException Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is invalid.
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is invalid.
Thrown when the ResourceOwnerPassword within HttpOAuthPasswordCredentials is invalid.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is invalid.
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is invalid.
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is invalid.
InvalidRequestException Thrown when the Uri within Soap Request is not in the correct format or contains invalid characters.
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is not in the correct format or contains invalid characters.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is not in the correct format or contains invalid characters.
Thrown when a header key in Headers within Soap Request is empty (i.e. "").
Thrown when a header key in Headers within Soap Request is restricted.
Thrown when a header key in Headers within Soap Request is restricted and forbidden.
Thrown when a header value in Headers within Soap Request could not be assigned to its restricted header key.
Thrown when a header value in Headers within Soap Request could not be converted to its restricted header key’s type.
Thrown when the Envelope in the SoapMessage within Soap Request is not valid XML.
Thrown when the HttpVersion within Soap Request is not one of the specified HttpRequestVersion values (e.g. (HttpRequestVersion)20).
InvalidResponseException Thrown when the ResponseEnvelope within Soap Response is not valid XML.
PropertyNullException Thrown when the Soap Request is null.
Thrown when the Uri within Soap Request is null.
Thrown when the SoapMessage within Soap Request is null.
Thrown when the Action in the Soap11Message within Soap Request is null.
Thrown when the Envelope in the SoapMessage within Soap Request is null.
Thrown when the Username within UserCredentials is null.
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is null.
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is null.
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is null.
Thrown when the ClientAuthentication within HttpOAuthClientCredentials is null.
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is null.
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is null.
PropertyEmptyException Thrown when the Uri within Soap Request is empty (i.e. "").
Thrown when the Username within UserCredentials is empty (i.e. "").
Thrown when the AccessTokenUri within HttpOAuthPasswordCredentials is empty (i.e. "").
Thrown when the ResourceOwnerUsername within HttpOAuthPasswordCredentials is empty (i.e. "").
Thrown when the AccessTokenUri within HttpOAuthClientCredentials is empty (i.e. "").
Thrown when the ClientId in ClientAuthentication within HttpOAuthClientCredentials is empty (i.e. "").
Thrown when the ClientSecret in ClientAuthentication within HttpOAuthClientCredentials is empty (i.e. "").

Remarks

Known Limitations

None

6.3.11 - Json

Blocks related to working with Json.

6.3.11.1 - Convert Json

Convert json to and from other data types.

6.3.11.1.1 - Convert Json To Object

Converts Json to an Object.
Icon

Convert Json To Object

(Cortex.Blocks.Json.ConvertJson.ConvertJsonToObjectBlock)

Description

Converts Json to an Object.

An additional Settings option can be specified to control how the conversion should deal with things such as:

  • null objects
  • Date Time formats and offsets
  • Number formats
  • Text escaping
  • Type information

For information about the default Settings used if none are specified, as well as all other options that can be configured, please see JsonSerializerSettings.

Examples

Convert Json to a List (without Type information)

This example will convert "[[1, 2, 3], [4, 5, 6]]" into a List<Object>.

Properties

Property Value Notes
Json ($)Json, with value "[[1, 2, 3], [4, 5, 6]]" ($)Json is a variable of type String
Settings ($)Settings, with value null ($)Settings is a variable of type JsonSerializerSettings
Object ($)Object, with no value ($)Object is a variable that will be set to a dynamic value (i.e. in this example to a List<Object>).

Result

Converting "[[1, 2, 3], [4, 5, 6]]" to an object results in the variable ($)Object being updated to the following:

[
    [
        1, 
        2, 
        3
    ], 
    [
        4, 
        5, 
        6
    ]
]

As the Json does not include any type information, ($)Object will be a List<Object>, rather than a List<List<Int32>>. This is because when performing the conversion there is no type information to tell the converter that the items in the list are List<Int32> data types.

See Convert Json to a List (with Type information) for an example on how to include type information in the Json.


Convert Json to a List (with Type information)

This example will convert "[[1, 2, 3], [4, 5, 6]]" into a List<List<Int32>>, rather than a List<Object> as above.

For this to work, type information needs to be included in the Json representation. This can be seen below:

{
    "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib",
    "$values": [
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [1,2,3]
        },
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [4,5,6]
        }
    ]
}

Realistically, this example is only useful if you have already produced Json including type information by using the Convert Object To Json block. If this is the case, you can then convert it back with the correct data types.

Properties

Property Value Notes
Json ($)Json, with complex value as shown above ($)Json is a variable of type String
Settings ($)Settings, with value new JsonSerializerSettings{TypeNameHandling = TypeNameHandling.All} ($)Settings is a variable of type JsonSerializerSettings
Object ($)Object, with no value ($)Object is a variable that will be set to a dynamic value (i.e. in this example to a List<List<Int32>>).

Result

Converting:

{
    "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib",
    "$values": [
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [1,2,3]
        },
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [4,5,6]
        }
    ]
}

to an object results in the variable ($)Object being updated to the following:

[
    [
        1, 
        2, 
        3
    ], 
    [
        4, 
        5, 
        6
    ]
]

As the Json does include type information, ($)Object will be a List<List<Int32>>, rather than a List<Object>.


Properties

Json

The Json to convert into an Object.

During the conversion it will be attempted to convert the Json to the correct data type where possible. If the correct data type cannot be determined, then collection data types will be converted to a List<dynamic>, and other objects will be converted to a Structure.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Json with no value

Settings

Optional Settings that can be specified to control how the conversion should deal with things such as:

  • null objects
  • Date Time formats and offsets
  • Number formats
  • Text escaping

For information about the default Settings used if none are specified, as well as all other options that can be configured, please see JsonSerializerSettings.

Data Type JsonSerializerSettings
Property Type Input
Is Advanced true
Default Editor Expression
Default Value new JsonSerializerSettings {}

Object

The Object that has been converted from Json.

Data Type dynamic
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Object with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
JsonReaderException Thrown when an error occurs reading the Json.
JsonSerializationException Thrown when an error occurs converting the Json to an Object.
PropertyEmptyException Thrown when Json is empty (i.e. "").
PropertyNullException Thrown when Json is null.

Remarks

“{}” Json

If Json is set to the text "{}", Object will be set to an empty Structure.

“[]” Json

If Json is set to the text "[]", Object will be set to an empty List<dynamic>.

“null” Json

If Json is set to the text "null", Object will be set to null.

Round-tripping

For most data types it should be possible to pass the Json created by a Convert Object To Json block to this block, and then pass the Object created by this block back to a Convert Object To Json block; this is called round-tripping.

It should be noted however, that not all data types will be able to be round-tripped.

An example of a data type that is not able to be round-tripped is HttpRequestHeaders. As it does not contain a public constructor it will not be able to be converted from its Json representation back into an HttpRequestHeaders; instead a JsonSerializationException will be thrown with a message like: "Cannot create and populate list type System.Net.Http.Headers.HttpRequestHeaders".

6.3.11.1.2 - Convert Object To Json

Converts an Object To Json.
Icon

Convert Object To Json

(Cortex.Blocks.Json.ConvertJson.ConvertObjectToJsonBlock)

Description

Converts an Object to Json.

An additional Settings option can be specified to control how the conversion should deal with things such as:

  • null objects
  • Date Time formats and offsets
  • Number formats
  • Text escaping
  • Type information

For information about the default Settings used if none are specified, as well as all other options that can be configured, please see JsonSerializerSettings.

Examples

Convert a List to Json (without Type information)

This example will convert [[1, 2, 3], [4, 5, 6]] to its Json representation, without including type information.

Properties

Property Value Notes
Object ($)Object, with value [[1, 2, 3], [4, 5, 6]] ($)Object is a variable of type List<List<Int32>>
Settings ($)Settings, with value null ($)Settings is a variable of type JsonSerializerSettings
Json ($)Json, with no value ($)Json is a variable that will be set to a String value.

Result

Converting [[1, 2, 3], [4, 5, 6]] to Json results in the variable ($)Json being updated to the following:

"[[1, 2, 3],[4, 5, 6]]"

As the resultant Json does not include any type information, if this Json was then used as input to the Convert Json To Object block, the resultant object would be a List<Object>, rather than a List<List<Int32>>.

See Convert a List To Json (with Type information) for an example on how to include type information in the Json.


Convert a List to Json (with Type information)

This example will convert [[1, 2, 3], [4, 5, 6]] to its Json representation, including type information.

Properties

Property Value Notes
Object ($)Object, with value [[1, 2, 3], [4, 5, 6]] ($)Object is a variable of type List<List<Int32>>
Settings ($)Settings, with value new JsonSerializerSettings{TypeNameHandling = TypeNameHandling.All} ($)Settings is a variable of type JsonSerializerSettings
Json ($)Json, with no value ($)Json is a variable that will be set to a String value.

Result

Converting [[1, 2, 3], [4, 5, 6]] to its Json representation (including type information) results in the variable ($)Json being updated to the following:

{
    "$type": "System.Collections.Generic.List`1[[System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib]], System.Private.CoreLib",
    "$values": [
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [1,2,3]
        },
        {
            "$type": "System.Collections.Generic.List`1[[System.Int32, System.Private.CoreLib]], System.Private.CoreLib",
            "$values": [4,5,6]
        }
    ]
}

Properties

Object

The Object to convert to Json.

Object can be any data type.

Data Type dynamic
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Object with no value

Settings

Optional Settings that can be specified to control how the conversion should deal with things such as:

  • null objects
  • Date Time formats and offsets
  • Number formats
  • Text escaping

For information about the default Settings used if none are specified, as well as all other options that can be configured, please see JsonSerializerSettings.

Data Type JsonSerializerSettings
Property Type Input
Is Advanced true
Default Editor Expression
Default Value new JsonSerializerSettings {Formatting = Formatting.Indented}

Json

The Json that has been converted from Object.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Json with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
JsonSerializationException Thrown when an error occurs converting the Object to Json.

Remarks

Object is empty Structure or Object

If Object is set to an empty Structure or Object, Json is set to the text "{}".

Object is empty List

If Object is set to an empty List, Json is set to the text "[]".

Null Object

If Object is set to null, Json will be set to the text "null".

Round-tripping

For most data types it should be possible to pass the Json created by this block to the Convert Json To Object block, and then pass the Object created by the Convert Json To Object block back to this block; this is called round-tripping.

It should be noted however, that not all data types will be able to be round-tripped.

An example of a data type that is not able to be round-tripped is HttpRequestHeaders. As it does not contain a public constructor it will not be able to be converted from its Json representation back into an HttpRequestHeaders; instead a JsonSerializationException will be thrown with a message like: "Cannot create and populate list type System.Net.Http.Headers.HttpRequestHeaders".

6.3.12 - Lists

Blocks related to working with Lists.

6.3.12.1 - Add Item(s)

Add an item or multiple items to a list.

6.3.12.1.1 - Add Item At Beginning

Adds an Item at the beginning of a List.
Icon

Add Item At Beginning

(Cortex.Blocks.Lists.AddItem.AddItemAtBeginningBlock`2)

Description

Adds an Item at the beginning of a List.

Examples

Add an Item at the beginning of an empty List

This example will add "New Item" at the beginning of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String

Result

Adding "New Item" at the beginning of [] results in the variable ($)List being updated to the following:

["New Item"]

Add an Item at the beginning of a List

This example will add "New Item" at the beginning of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String

Result

Adding "New Item" at the beginning of ["Some Text", 1] results in the variable ($)List being updated to the following:

["New Item", "Some Text", 1]

Properties

List

The List where the Item is added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Item

The Item to be added at the beginning of the List.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Item is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.1.2 - Add Item At End

Adds an Item at the end of a List.
Icon

Add Item At End

(Cortex.Blocks.Lists.AddItem.AddItemAtEndBlock`2)

Description

Adds an Item at the end of a List.

Examples

Add an Item at the end of an empty List

This example will add "New Item" at the end of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String

Result

Adding "New Item" at the end of [] results in the variable ($)List being updated to the following:

["New Item"]

Add an Item at the end of a List

This example will add "New Item" at the end of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String

Result

Adding "New Item" at the end of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text", 1, "New Item"]

Properties

List

The List where the Item is added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Item

The Item to be added at the end of the List.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Item is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.1.3 - Add Item At Index

Adds an Item at the specified Index of a List.
Icon

Add Item At Index

(Cortex.Blocks.Lists.AddItem.AddItemAtIndexBlock`2)

Description

Adds an Item at the specified Index of a List.

Examples

Add an Item at the first Index (i.e. 0) of an empty List

This example will add "New Item" at index 0 of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding "New Item" at index 0 of [] results in the variable ($)List being updated to the following:

["New Item"]

Add an Item at the first Index (i.e. 0) of a List

This example will add "New Item" at index 0 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding "New Item" at index 0 of ["Some Text", 1] results in the variable ($)List being updated to the following:

["New Item", "Some Text", 1]

Add an Item at the end (i.e. Index equals count of items) of a List

This example will add "New Item" at index 2 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with value "New Item" ($)Item is a variable of type String
Index ($)Index, with value 2 ($)Index is a variable of type Int32

Result

Adding "New Item" at index 2 of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text", 1, "New Item"]

Properties

List

The List where the Item is added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Item

The Item to be added at the specified Index of the List.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Index

The Index to add the Item at.

Valid values are between and including 0 and the total count of items in the List.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Item is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Index is out of the range of the list indexes. Valid indexes are between and including 0 and the count of items in the List.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.1.4 - Add Items At Beginning

Adds Items at the beginning of a List.
Icon

Add Items At Beginning

(Cortex.Blocks.Lists.AddItem.AddItemsAtBeginningBlock`2)

Description

Adds Items at the beginning of a List.

Examples

Add Items at the beginning of an empty List

This example will add ["New Item 1", "New Item 2"] at the beginning of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>

Result

Adding ["New Item 1", "New Item 2"] at the beginning of [] results in the variable ($)List being updated to the following:

["New Item 1", "New Item 2"]

Add Items at the beginning of a List

This example will add ["New Item 1", "New Item 2"] at the beginning of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>

Result

Adding ["New Item 1", "New Item 2"] at the beginning of ["Some Text", 1] results in the variable ($)List being updated to the following:

["New Item 1", "New Item 2", "Some Text", 1]

Properties

List

The List where the Items are added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Items

The Items to be added at the beginning of the List.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List or Items is null.

Remarks

Empty Items

If Items is empty (i.e. []) there is nothing to add, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.1.5 - Add Items At End

Adds Items at the end of a List.
Icon

Add Items At End

(Cortex.Blocks.Lists.AddItem.AddItemsAtEndBlock`2)

Description

Adds Items at the end of a List.

Examples

Add Items at the end of an empty List

This example will add ["New Item 1", "New Item 2"] at the end of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>

Result

Adding ["New Item 1", "New Item 2"] at the end of [] results in the variable ($)List being updated to the following:

["New Item 1", "New Item 2"]

Add Items at the end of a List

This example will add ["New Item 1", "New Item 2"] at the end of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>

Result

Adding ["New Item 1", "New Item 2"] at the end of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text", 1, "New Item 1", "New Item 2"]

Properties

List

The List where the Items are added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Items

The Items to be added at the end of the List.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List or Items is null.

Remarks

Empty Items

If Items is empty (i.e. []) there is nothing to add, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.1.6 - Add Items At Index

Adds Items at the specified Index of a List.
Icon

Add Items At Index

(Cortex.Blocks.Lists.AddItem.AddItemsAtIndexBlock`2)

Description

Adds Items at the specified Index of a List.

Examples

Add Items at the first index (i.e. 0) of an empty List

This example will add ["New Item 1", "New Item 2"] at index 0 of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding ["New Item 1", "New Item 2"] at index 0 of [] results in the variable ($)List being updated to the following:

["New Item 1", "New Item 2"]

Add Items at the first Index (i.e. 0) of a List

This example will add ["New Item 1", "New Item 2"] at index 0 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding ["New Item 1", "New Item 2"] at index 0 of ["Some Text", 1] results in the variable ($)List being updated to the following:

["New Item 1", "New Item 2", "Some Text", 1]

Add Items at the end (i.e. Index equals count of items) of a List

This example will add ["New Item 1", "New Item 2"] at index 2 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Items ($)Items, with value ["New Item 1", "New Item 2"] ($)Items is a variable of type IEnumerable<String>
Index ($)Index, with value 2 ($)Index is a variable of type Int32

Result

Adding ["New Item 1", "New Item 2"] at index 2 of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text", 1, "New Item 1", "New Item 2"]

Properties

List

The List where the Items are added.

List can be any IList<TItem>, where TItem represents the type of items that can be added to the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Items

The Items to be added at the specified Index of the List.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Index

The Index to add the Items at.

Valid values are between and including 0 and the total count of items in the List.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List or Items is null.
PropertyValueOutOfRangeException Thrown when Index is out of the range of the list indexes. Valid indexes are between and including 0 and the count of items in the List.

Remarks

Empty Items

If Items is empty (i.e. []) there is nothing to add, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.2 - Contains Item(s)

Check if an item or multiple items are contained in a list.

6.3.12.2.1 - Contains Item With Value

Checks if a List contains at least one item matching the specified value.
Icon

Contains Item With Value

(Cortex.Blocks.Lists.ContainsItem.ContainsItemWithValueBlock`2)

Description

Checks if List contains at least one item matching Value.

Examples

List contains item with Value

This example will check whether [1, 2, 3, 3, 2, 1] contains the value 1.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

[1, 2, 3, 3, 2, 1] contains two items with the value 1. Therefore, the variable ($)ContainsItem will be updated to the following:

true

List does not contain item with Value

This example will check whether [1, 2, 3, 3, 2, 1] contains the value 10.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 10 ($)Value is a variable of type Int32
Contains Item ($)ContainsItem, with no value ($)ContainsItem is a variable that will be set to a Boolean value

Result

[1, 2, 3, 3, 2, 1] does not contain any items with the value 10. Therefore, the variable ($)ContainsItem will be updated to the following:

false

Properties

List

The List to check whether it contains at least one item matching the specified Value.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value to check for matching items.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Item

The result of the contains item check.

If List contains at least one item matching the specified Value, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItem with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []), the variable specified in the Contains Item property is set to false.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.2.2 - Contains Items With Values

Checks if a List contains at least one item matching each of the specified values.
Icon

Contains Items With Values

(Cortex.Blocks.Lists.ContainsItem.ContainsItemsWithValuesBlock`2)

Description

Checks if List contains at least one item matching each of the specified Values.

Examples

List contains items with Values

This example will check whether [1, 2, 3, 3, 2, 1] contains at least one item matching each of the values in [1, 2, 3].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Values ($)Values, with value [1, 2, 3] ($)Values is a variable of type IEnumerable<Int32>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

[1, 2, 3, 3, 2, 1] contains at least one item matching each of the values in [1, 2, 3]; it contains two items with the value 1, two items with the value 2 and two items with the value 3. Therefore, the variable ($)ContainsItems will be updated to the following:

true

List does not contain items with Values

This example will check whether [1, 2, 3, 3, 2, 1] contains at least one item matching each of the values in [1, 2, 3, 10].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Values ($)Values, with value [1, 2, 3, 10] ($)Values is a variable of type IEnumerable<Int32>
Contains Items ($)ContainsItems, with no value ($)ContainsItems is a variable that will be set to a Boolean value

Result

[1, 2, 3, 3, 2, 1] does not contain at least one item matching each of the values in [1, 2, 3, 10]; it contains two items with the value 1, two items with the value 2 and two items with the value 3, but no items with the value 10. Therefore, the variable ($)ContainsItems will be updated to the following:

false

Properties

List

The List to check whether it contains at least one item matching each of the specified Values.

Items are considered matching if they have a value matching one of the specified Values.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Values

The Values to check for matching items.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Contains Items

The result of the contains items check.

If List contains at least one item matching each of the specified Values, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsItems with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List or Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []), the variable specified in the Contains Items property is set to false.

Empty Values

If Values is empty (i.e. []), the variable specified in the Contains Items property is set to false.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.3 - Get Count(s) of Items

Get the count(s) of items in a list.

6.3.12.3.1 - Get Count Of All Items

Gets the count of all items in a List.
Icon

Get Count Of All Items

(Cortex.Blocks.Lists.GetCount.GetCountOfAllItemsBlock`2)

Description

Gets the Count of all items in a List.

Examples

Get Count of all items in a List

This example will get the count of all items in ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Count ($)Count, with no value ($)Count is a variable that will be set to an Int32 value

Result

Getting the count of all items in ["Some Text", 1] results in the variable ($)Count being updated to the following:

2

Properties

List

The List to get the Count of all items for.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Count

The Count of all items in List.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Count with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []), the variable specified in the Count property is set to 0.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.3.2 - Get Count Of Items With Value

Gets the count of items in a List with the specified value.
Icon

Get Count Of Items With Value

(Cortex.Blocks.Lists.GetCount.GetCountOfItemsWithValueBlock`2)

Description

Gets the Count of items in a List with the specified Value.

Examples

Get Count of items in a List with a Value

This example will get the count of items in ["Some Text", 1] with the value 1.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Count ($)Count, with no value ($)Count is a variable that will be set to an Int32 value

Result

Getting the count of items in ["Some Text", 1] with the value 1 results in the variable ($)Count being updated to the following:

1

Properties

List

The List to get the Count of items with the specified Value for.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value items must match to be included in the Count.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Count

The Count of items in List with the specified Value.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Count with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []), the variable specified in the Count property is set to 0.

No items matching Value

If List does not contain items matching the specified Value, the variable specified in the Count property is set to 0.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.3.3 - Get Counts Of Items With Values

Gets the counts of items in a List matching each of the specified values.
Icon

Get Counts Of Items With Values

(Cortex.Blocks.Lists.GetCount.GetCountsOfItemsWithValuesBlock`2)

Description

Gets the Counts of items in a List matching each of the specified Values.

Examples

Get Counts of items in a List matching each of the Values

This example will get the counts of items in ["Some Text", 1] matching each of the values [1, 2, 3].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Values ($)Values, with value [1, 2, 3] ($)Values is a variable of type IEnumerable<Int32>
Counts ($)Counts, with no value ($)Counts is a variable that will be set to an IList<Int32> value

Result

Getting the counts of items in ["Some Text", 1] matching each of the values [1, 2, 3] results in the variable ($)Counts being updated to the following:

[1, 0, 0]

The counts of items matching each value are added to ($)Counts at the same index the value is in ($)Values. In this example, there is one item matching the first value 1, zero items matching the second value 2 and zero items matching the third value 3, resulting in ($)Counts being set to [1, 0, 0].


Properties

List

The List to get the Counts of items matching each of the specified Values for.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Values

The Values items must match to be included in the Counts.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Counts

The Counts of items in List matching each of the specified Values.

For each value in Values, Counts will have a corresponding item whose value is the count of items in List matching the value.

I.e. The count of items matching the first value in Values will be saved as the first item in Counts; the count of items matching the second value in Values will be saved as the second item in Counts etc.

Data Type IList<Int32>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Counts with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List or Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty Values

If Values is empty (i.e. []), the variable specified in the Counts property is set to empty (i.e. []).

No items matching a specified value in Values

If List does not contain items matching one of the specified Values, 0 is written to the corresponding item in Counts for that value.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.4 - Get Index(es) of Items

Get the index of an item or indexes of multiple items contained in a list.

6.3.12.4.1 - Get Index Of Item With Value

Gets the index of the specified occurrence of an item in a List matching a value.
Icon

Get Index Of Item With Value

(Cortex.Blocks.Lists.GetIndex.GetIndexOfItemWithValueBlock`2)

Description

Gets the Index of the specified Occurrence of an item in a List matching a Value.

Examples

Get the Index of the first Occurrence of an item in a List matching a Value

This example will attempt to get the index of the first occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of 1 means the first occurrence; 2 means second etc.

Attempting to get the index of the first occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)Index being updated to the following:

0

Get the Index of the last Occurrence of an item in a List matching a Value

This example will attempt to get the index of the last occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of -1, means the last occurrence; -2 means second last etc.

Attempting to get the index of the last occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)List being updated to the following:

5

Properties

List

The List to get the Index of the specified Occurrence of matching item from.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the item to get the Index of the specified Occurrence must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to get the Index of.

Items are considered matching if they have the specified Value.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Index

Int32 indicating the Index of the specified Occurrence of item matching Value in List.

If there is no specified Occurrence of item matching Value in List, the specified variable will be set to -1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Index with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Occurrences

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty List

If List is empty (i.e. []), the variable specified in the Index property is set to -1.

No items matching Value, or Occurrence is not present

If List does not contain items matching the specified Value or the specified Occurrence is not present, the variable specified in the Index property is set to -1.

Occurrence is zero

If the Occurrence is set to 0, the variable specified in the Index property is set to -1.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.4.2 - Get Indexes Of Items With Value

Gets the indexes of all items in a List matching a value.
Icon

Get Indexes Of Items With Value

(Cortex.Blocks.Lists.GetIndex.GetIndexesOfItemsWithValueBlock`2)

Description

Gets the Indexes of all items in a List matching a Value.

Examples

Get the Indexes of all items in a List matching a Value

This example will attempt to get the indexes of all items matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

Attempting to get the indexes of all items matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)Indexes being updated to the following:

[0, 5]

Properties

List

The List to get the Indexes of matching items from.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the items to get the Indexes of must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Indexes

IList<Int32> containing the Indexes of items matching Value in List.

If there are no items matching Value in List, the specified variable will be set to [-1].

For information about what an index is, please see Indexes.

Data Type IList<Int32>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Indexes with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []), the variable specified in the Indexes property is set to [-1].

No items matching Value

If List does not contain items matching the specified Value, the variable specified in the Indexes property is set to [-1].

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5 - Get Item(s)

Get an item or multiple items from a list.

6.3.12.5.1 - Get Item At Beginning

Gets the item at the beginning of a List.
Icon

Get Item At Beginning

(Cortex.Blocks.Lists.GetItem.GetItemAtBeginningBlock`2)

Description

Gets the Item at the beginning of a List.

Examples

Get the Item at the beginning of a List

This example will get the item at the beginning of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. String)

Result

Getting the item at the beginning of ["Some Text", 1] results in the variable ($)Item being updated to the following:

"Some Text"

Properties

List

The List to get the item from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Item

The Item at the beginning of List.

Data Type TItem
Property Type Output
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.2 - Get Item At End

Gets the item at the end of a List.
Icon

Get Item At End

(Cortex.Blocks.Lists.GetItem.GetItemAtEndBlock`2)

Description

Gets the Item at the end of a List.

Examples

Get the Item at the end of a List

This example will get the item at the end of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. Int32)

Result

Getting the item at the end of ["Some Text", 1] results in the variable ($)Item being updated to the following:

1

Properties

List

The List to get the item from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Item

The Item at the end of List.

Data Type TItem
Property Type Output
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.3 - Get Item At Index

Gets the item at the specified index of a List.
Icon

Get Item At Index

(Cortex.Blocks.Lists.GetItem.GetItemAtIndexBlock`2)

Description

Gets the Item at the specified Index of a List.

Examples

Get the Item at the first Index (i.e. 0) of a List

This example will get the item at index 0 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. String)

Result

Getting the item at index 0 of ["Some Text", 1] results in the variable ($)Item being updated to the following:

"Some Text"

Get the Item at the last Index (i.e. Index equals count of items - 1) of a List

This example will get the item at index 1 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 1 ($)Index is a variable of type Int32
Item ($)Item, with no value ($)Item is a variable that will be set to the type of the item (i.e. Int32)

Result

Getting the item at index 1 of ["Some Text", 1] results in the variable ($)Item being updated to the following:

1

Properties

List

The List to get the item from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Index

The Index to get the item at.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Item

The Item at the specified Index of List.

Data Type TItem
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Item with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when List contains no items.
Thrown when Index is out of the range of the list indexes. Valid indexes are between and including 0 and the count of items in the List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.4 - Get Items At Beginning

Gets a count of items at the beginning of a List.
Icon

Get Items At Beginning

(Cortex.Blocks.Lists.GetItem.GetItemsAtBeginningBlock`2)

Description

Gets the specified Count of Items at the beginning of a List.

Examples

Get Count of Items at the beginning of a List

This example will get 2 items at the beginning of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Count ($)Count, with value 2 ($)Count is a variable of type Int32
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<dynamic> value

Result

Getting 2 items from the beginning of ["Some Text", 1, "Some More Text", 2] results in the variable ($)Items being updated to the following:

["Some Text", 1]

Properties

List

The List to get the Items from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Count

The Count of Items to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Items

The Items at the beginning of List.

Items will be in the same order they are defined in List.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Count is greater than the count of items in the List - 1.

Remarks

Negative Count

If Count is negative, Items contains all items in the List.

Zero Count

If Count is 0, Items is set to an empty list (i.e. []).

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.5 - Get Items At End

Gets a count of items at the end of a List.
Icon

Get Items At End

(Cortex.Blocks.Lists.GetItem.GetItemsAtEndBlock`2)

Description

Gets the specified Count of Items at the end of a List.

Examples

Get Count of Items at the end of a List

This example will get 2 items at the end of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Count ($)Count, with value 2 ($)Count is a variable of type Int32
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<dynamic> value

Result

Getting 2 items from the end of ["Some Text", 1, "Some More Text", 2] results in the variable ($)Items being updated to the following:

["Some More Text", 2]

Properties

List

The List to get the Items from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Count

The Count of Items to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Items

The Items at the end of List.

Items will be in the same order they are defined in List.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Count is greater than the count of items in the List - 1.

Remarks

Negative Count

If Count is negative, Items contains all items in the List.

Zero Count

If Count is 0, Items is set to an empty list (i.e. []).

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.6 - Get Items At Index

Gets a count of items starting at the specified index of a List.
Icon

Get Items At Index

(Cortex.Blocks.Lists.GetItem.GetItemsAtIndexBlock`2)

Description

Gets the specified Count of Items starting at the given Index of a List.

Examples

Get Count of Items at the first Index (i.e. 0) of a List

This example will get 2 items at index 0 of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32
Count ($)Count, with value 2 ($)Count is a variable of type Int32
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<dynamic> value

Result

Getting 2 items at index 0 of ["Some Text", 1, "Some More Text", 2] results in the variable ($)Items being updated to the following:

["Some More", 1]

Properties

List

The List to get the Items from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Index

The Index to get the Count of Items at. This is an inclusive index, which means the item at the specified index will be included.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Count

The Count of Items to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Items

The Items at the specified Index of List.

Items will be in the same order they are defined in List.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Index is less than 0 or greater than the count of items in List - 1.
Thrown when Index + Count is greater than the count of items in the List - 1.

Remarks

Index is inclusive

The Index is an inclusive index, which means the item at the index will be included in Items.

Negative Count

If Count is negative, Items contains all items after and including the item at the specified Index in the List.

Zero Count

If Count is 0, Items is set to an empty list (i.e. []).

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.5.7 - Get Items At Indexes

Gets the items at each of the specified indexes of a List.
Icon

Get Items At Indexes

(Cortex.Blocks.Lists.GetItem.GetItemsAtIndexesBlock`2)

Description

Gets the Items at each of the specified Indexes of a List.

Examples

Get Items at the first and third Indexes (i.e. [0, 2]) of a List

This example will get items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Indexes ($)Indexes, with value [0, 2] ($)Indexes is a variable of type IEnumerable<Int32>
Items ($)Items, with no value ($)Items is a variable that will be set to an IList<dynamic> value

Result

Getting items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2] results in the variable ($)Items being updated to the following:

["Some Text", "Some More Text"]

Properties

List

The List to get the Items from.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Indexes

The Indexes of the Items to get.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type IEnumerable<Int32>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<int>() {}

Items

The Items at the specified Indexes of List.

Items will be in the order they are defined in Indexes.

Data Type IList<TItem>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Items with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
DuplicateValueException Thrown when Indexes contains duplicate values.
PropertyNullException Thrown when List or Indexes is null.
PropertyValueOutOfRangeException Thrown when Indexes contains no values.
Thrown when any index in Indexes is less than 0 or greater than the count of items in List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6 - Remove Item(s)

Remove an item or multiple items from a list.

6.3.12.6.1 - Remove All Items

Removes all items from a List.
Icon

Remove All Items

(Cortex.Blocks.Lists.RemoveItem.RemoveAllItemsBlock`2)

Description

Removes all items from a List.

Examples

Remove all items from an empty List

This example will attempt to remove all items from [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>

Result

Attempting to remove all items from [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove all items from a List

This example will remove all items from ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>

Result

Removing all items from ["Some Text", 1] results in the variable ($)List being updated to the following:

[]

Properties

List

The List where all items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.2 - Remove Duplicate Items

Removes duplicate items from a List.
Icon

Remove Duplicate Items

(Cortex.Blocks.Lists.RemoveItem.RemoveDuplicateItemsBlock`2)

Description

Removes duplicate items from a List.

Examples

Remove duplicate items from an empty List

This example will attempt to remove duplicate items from [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>

Result

Attempting to remove duplicate items from [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove duplicate items from a List without duplicates

This example will attempt to remove duplicate items from ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>

Result

Attempting to remove duplicate items from ["Some Text", 1] results in no operation, as there are no duplicates to remove. Therefore, the variable ($)List remains:

["Some Text", 1]

Remove duplicate items from a List containing duplicates

This example will remove duplicate items from ["Some Text", 1, "Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some Text", 1] ($)List is a variable of type IList<dynamic>

Result

Removing duplicate items from ["Some Text", 1, "Some Text", 1] results in the second occurrences of "Some Text" and 1 being removed; with the variable ($)List being updated to the following:

["Some Text", 1]

Properties

List

The List where duplicate items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

For information and examples of how it is determined whether two items are considered the same, please see Object Equality.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

List with no duplicates

If List does not contain duplicates there is nothing to remove, so no operation is performed.

Which duplicates are removed?

If List contains duplicates, the first occurrences of the duplicated items are kept; all other occurrences are removed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.3 - Remove Item At Beginning

Removes the item at the beginning of a List.
Icon

Remove Item At Beginning

(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtBeginningBlock`2)

Description

Removes the item at the beginning of a List.

Examples

Remove the Item at the beginning of an empty List

This example will attempt to remove the item at the beginning of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>

Result

Attempting to remove the item at the beginning of [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove the Item at the beginning of a List

This example will remove the item at the beginning of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>

Result

Removing the item at the beginning of ["Some Text", 1] results in the variable ($)List being updated to the following:

[1]

Properties

List

The List where the item is removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.4 - Remove Item At End

Removes the item at the end of a List.
Icon

Remove Item At End

(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtEndBlock`2)

Description

Removes the item at the end of a List.

Examples

Remove the Item at the end of an empty List

This example will attempt to remove the item at the end of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>

Result

Attempting to remove the item at the end of [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove the Item at the end of a List

This example will remove the item at the end of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>

Result

Removing the item at the end of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text"]

Properties

List

The List where the item is removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.5 - Remove Item At Index

Removes the item at the specified index of a List.
Icon

Remove Item At Index

(Cortex.Blocks.Lists.RemoveItem.RemoveItemAtIndexBlock`2)

Description

Removes the item at the specified Index of a List.

Examples

Remove the Item at the first Index (i.e. 0) of an empty List

This example will attempt to remove the item at index 0 of [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Attempting to remove the item at index 0 of [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove the Item at the first Index (i.e. 0) of a List

This example will remove the item at index 0 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Removing the item at index 0 of ["Some Text", 1] results in the variable ($)List being updated to the following:

[1]

Remove the Item at the last Index (i.e. Index equals count of items - 1) of a List

This example will remove the item at index 1 of ["Some Text", 1].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 1 ($)Index is a variable of type Int32

Result

Remove the item at index 1 of ["Some Text", 1] results in the variable ($)List being updated to the following:

["Some Text"]

Properties

List

The List where the item is removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Index

The Index to remove the item at.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Index is out of the range of the list indexes. Valid indexes are between and including 0 and the count of items in the List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.6 - Remove Item With Value

Removes the specified occurrence of an item matching a value from a List.
Icon

Remove Item With Value

(Cortex.Blocks.Lists.RemoveItem.RemoveItemWithValueBlock`2)

Description

Removes the specified Occurrence of an item matching a Value from a List.

Examples

Remove the first Occurrence of an item matching a Value from an empty List

This example will attempt to remove the first occurrence of an item matching the value 1 from [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

Attempting to remove the first occurrence of an item matching the value 1 from [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove the first Occurrence of an item matching a Value from a List

This example will attempt to remove the first occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means remove the first occurrence; 2 means second etc.

Attempting to remove the first occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)List being updated to the following:

[2, 3, 3, 2, 1]

Remove the last Occurrence of an item matching a Value from a List

This example will attempt to remove the last occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1, means remove the last occurrence; -2 means second last etc.

Attempting to remove the last occurrence of an item matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)List being updated to the following:

[1, 2, 3, 3, 2]

Properties

List

The List to remove the specified Occurrence of matching item from.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the item to remove must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to remove from the List.

Items are considered matching if they have the specified Value.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Occurrences

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

No items matching Value, or Occurrence is not present

If List does not contain items matching the specified Value or the specified Occurrence is not present, there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.7 - Remove Items At Beginning

Removes a count of items from the beginning of a List.
Icon

Remove Items At Beginning

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtBeginningBlock`2)

Description

Removes the specified Count of items from the beginning of a List.

Examples

Remove Count of items from the beginning of a List

This example will remove 2 items from the beginning of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Count ($)Count, with value 2 ($)Count is a variable of type Int32

Result

Removing 2 items from the beginning of ["Some Text", 1, "Some More Text", 2] results in the variable ($)List being updated to the following:

["Some More Text", 2]

Properties

List

The List where the items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Count

The Count of items to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Count is greater than the count of items in the List - 1.

Remarks

Negative Count

If Count is negative all items in the List are removed.

Zero Count

If Count is 0 there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.8 - Remove Items At End

Removes a count of items from the end of a List.
Icon

Remove Items At End

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtEndBlock`2)

Description

Removes the specified Count of items from the end of a List.

Examples

Remove Count of items from the end of a List

This example will remove 2 items from the end of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Count ($)Count, with value 2 ($)Count is a variable of type Int32

Result

Removing 2 items from the end of ["Some Text", 1, "Some More Text", 2] results in the variable ($)List being updated to the following:

["Some Text", 1]

Properties

List

The List where the items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Count

The Count of items to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Count is greater than the count of items in the List - 1.

Remarks

Negative Count

If Count is negative all items in the List are removed.

Zero Count

If Count is 0 there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.9 - Remove Items At Index

Removes a count of items starting at the specified index of a List.
Icon

Remove Items At Index

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtIndexBlock`2)

Description

Removes the specified Count of items starting at the given Index of a List.

Examples

Remove Count of items at the first Index (i.e. 0) of a List

This example will remove 2 items at index 0 of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32
Count ($)Count, with value 2 ($)Count is a variable of type Int32

Result

Removing 2 items at index 0 of ["Some Text", 1, "Some More Text", 2] results in the variable ($)List being updated to the following:

["Some More Text", 2]

Properties

List

The List where the items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Index

The Index to remove the Count of items at. This is an inclusive index, which means the item at the specified index will be included.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Count

The Count of items to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when Index is less than 0 or greater than the count of items in List - 1.
Thrown when Index + Count is greater than the count of items in the List - 1.

Remarks

Index is inclusive

The Index is an inclusive index, which means the item at the index will be included in the removed items.

Negative Count

If Count is negative all items after and including the specified Index in the List are removed.

Zero Count

If Count is 0 there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.10 - Remove Items At Indexes

Removes the items at each of the specified indexes of a List.
Icon

Remove Items At Indexes

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsAtIndexesBlock`2)

Description

Removes the items at each of the specified Indexes of a List.

Examples

Remove items at the first and third Indexes (i.e. [0, 2]) of a List

This example will remove items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2].

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
Indexes ($)Indexes, with value [0, 2] ($)Indexes is a variable of type IEnumerable<Int32>

Result

Removing items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2] results in the variable ($)List being updated to the following:

[1, 2]

Properties

List

The List where the items are removed from.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Indexes

The Indexes of the items to remove.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type IEnumerable<Int32>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<int>() {}

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
DuplicateValueException Thrown when Indexes contains duplicate values.
PropertyNullException Thrown when List or Indexes is null.
PropertyValueOutOfRangeException Thrown when Indexes contains no values.
Thrown when any index in Indexes is less than 0 or greater than the count of items in List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.11 - Remove Items With Value

Removes all items matching a value from a List.
Icon

Remove Items With Value

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsWithValueBlock`2)

Description

Removes all items matching a Value from a List.

Examples

Remove all items matching a Value from an empty List

This example will attempt to remove all items matching the value 1 from [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Value ($)Value, with value 1 ($)Value is a variable of type Int32

Result

Attempting to remove all items matching the value 1 from [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove all items matching a Value from a List

This example will attempt to remove all items matching the value 1 from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32

Result

Attempting to remove all items matching the value 1 from [1, 2, 3, 3, 2, 1] results in the variable ($)List being updated to the following:

[2, 3, 3, 2]

Properties

List

The List to remove all matching items from.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the items to remove must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

No items matching Value

If List does not contain items matching the specified Value, there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.6.12 - Remove Items With Values

Removes all items matching one of the specified values from a List.
Icon

Remove Items With Values

(Cortex.Blocks.Lists.RemoveItem.RemoveItemsWithValuesBlock`2)

Description

Removes all items matching one of the specified Values from a List.

Examples

Remove all items matching one of the specified Values from an empty List

This example will attempt to remove all items matching one of the values [1, 2] from [].

Properties

Property Value Notes
List ($)List, with value [] ($)List is a variable of type IList<dynamic>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>

Result

Attempting to remove all items matching one of the values [1, 2] from [] results in no operation, as there is nothing to remove. Therefore, the variable ($)List remains:

[]

Remove all items matching one of the specified Values from a List

This example will attempt to remove all items matching one of the values [1, 2] from [1, 2, 3, 3, 2, 1].

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>

Result

Attempting to remove all items matching one of the values [1, 2] from [1, 2, 3, 3, 2, 1] results in the variable ($)List being updated to the following:

[3, 3]

Properties

List

The List to remove all matching items from.

Items are considered matching if they have one of the specified Values.

List can be any IList<TItem>, where TItem represents the type of items that can be removed from the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Values

The Values the items to remove must match one of.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyNullException Thrown when List or Values is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []) there is nothing to remove, so no operation is performed.

Empty Values

If Values is empty (i.e. []) there are no values to match, therefore nothing can be removed and no operation is performed.

No items matching a specified value in Values

If List does not contain items matching one of the specified Values, there is nothing to remove for that value.

No items matching Values

If List does not contain items matching any of the specified Values, there is nothing to remove, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7 - Set Item(s)

Set an item or multiple items in a list to a new value.

6.3.12.7.1 - Set All Items

Sets all items in a List to a new value.
Icon

Set All Items

(Cortex.Blocks.Lists.SetItem.SetAllItemsBlock`2)

Description

Sets all items in a List to a New Value.

Examples

Set all items in a List to a New Value

This example will set all items in ["Some Text", 1] to "New Value".

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
New Value ($)NewValue, with value "New Value" ($)NewValue is a variable of type String

Result

Setting all items in ["Some Text", 1] to "New Value" results in the variable ($)List being updated to the following:

["New Value", "New Value"]

Properties

List

The List to set all items in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Value

The New Value to set all items in List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when New Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Empty List

If List is empty (i.e. []) there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.2 - Set Item At Beginning

Sets the item at the beginning of a List to a new value.
Icon

Set Item At Beginning

(Cortex.Blocks.Lists.SetItem.SetItemAtBeginningBlock`2)

Description

Sets the item at the beginning of a List to a New Value.

Examples

Set the item at the beginning of a List to a New Value

This example will set the item at the beginning of ["Some Text", 1] to "Some Modified Text".

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
New Value ($)NewValue, with value "Some Modified Text" ($)NewValue is a variable of type String

Result

Setting the item at the beginning of ["Some Text", 1] to "Some Modified Text" results in the variable ($)List being updated to the following:

["Some Modified Text", 1]

Properties

List

The List to set the item in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Value

The New Value to set the item at the beginning of List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when New Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.3 - Set Item At End

Sets the item at the end of a List to a new value.
Icon

Set Item At End

(Cortex.Blocks.Lists.SetItem.SetItemAtEndBlock`2)

Description

Sets the item at the end of a List to a New Value.

Examples

Set the item at the end of a List to a New Value

This example will set the item at the end of ["Some Text", 1] to 10.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32

Result

Setting the item at the end of ["Some Text", 1] to 10 results in the variable ($)List being updated to the following:

["Some Text", 10]

Properties

List

The List to set the item in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Value

The New Value to set the item at the end of List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when New Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List is null.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.4 - Set Item At Index

Sets the item at the specified index of a List to a new value.
Icon

Set Item At Index

(Cortex.Blocks.Lists.SetItem.SetItemAtIndexBlock`2)

Description

Sets the item at the specified Index of a List to a New Value.

Examples

Set the Item at the first Index (i.e. 0) of a List to a New Value

This example will set the item at index 0 of ["Some Text", 1] to 10.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Setting the item at index 0 of ["Some Text", 1] to 10 results in the variable ($)List being updated to the following:

[10, 1]

Set the Item at the last Index (i.e. Index equals count of items - 1) of a List

This example will set the item at index 1 of ["Some Text", 1] to 10.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1] ($)List is a variable of type IList<dynamic>
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Index ($)Index, with value 1 ($)Index is a variable of type Int32

Result

Setting the item at index 1 of ["Some Text", 1] to 10 results in the variable ($)List being updated to the following:

["Some Text", 10]

Properties

List

The List to set the item in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Value

The New Value to set the item at the specified Index of List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Index

The Index to set the item at.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when New Value is null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.
PropertyValueOutOfRangeException Thrown when List contains no items.
Thrown when Index is out of the range of the list indexes. Valid indexes are between and including 0 and the count of items in the List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.5 - Set Item With Value

Sets the specified occurrence of an item matching a value in a List to a new value.
Icon

Set Item With Value

(Cortex.Blocks.Lists.SetItem.SetItemWithValueBlock`2)

Description

Sets the specified Occurrence of an item matching a Value in a List to a New Value.

Examples

Set the first Occurrence of an item matching a Value in a List to a New Value

This example will attempt to set the first occurrence of an item matching the value 1 in [1, 2, 3, 3, 2, 1] to 10.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of 1 means set the first occurrence; 2 means second etc.

Attempting to set the first occurrence of an item matching the value 1 in [1, 2, 3, 3, 2, 1] to 10 results in the variable ($)List being updated to the following:

[10, 2, 3, 3, 2, 1]

Set the last Occurrence of an item matching a Value in a List to a New Value

This example will attempt to set the last occurrence of an item matching the value 1 in [1, 2, 3, 3, 2, 1] to 10.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32

Result

An Occurrence of -1, means set the last occurrence; -2 means second last etc.

Attempting to set the last occurrence of an item matching the value 1 in [1, 2, 3, 3, 2, 1] to 10 results in the variable ($)List being updated to the following:

[1, 2, 3, 3, 2, 10]

Properties

List

The List to set the specified Occurrence of matching item in.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the item to set must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set the specified Occurrence of matching item in List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Occurrence

The Occurrence of matching item to set in the List.

Items are considered matching if they have the specified Value.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Value or New Value are null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Occurrences

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Empty List

If List is empty (i.e. []) there is nothing to set, so no operation is performed.

No items matching Value, or Occurrence is not present

If List does not contain items matching the specified Value or the specified Occurrence is not present, there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.6 - Set Items At Beginning

Sets the items at the beginning of a List to new values.
Icon

Set Items At Beginning

(Cortex.Blocks.Lists.SetItem.SetItemsAtBeginningBlock`2)

Description

Sets the items at the beginning of a List to New Values.

Examples

Set the items at the beginning of a List to New Values

This example will set the first and second items at the beginning of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
New Values ($)NewValues, with value ["Some Modified Text", 10] ($)NewValues is a variable of type IEnumerable<dynamic>

Result

Setting the first and second items at the beginning of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively, results in the variable ($)List being updated to the following:

["Some Modified Text", 10, "Some More Text", 2]

Properties

List

The List to set the items in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Values

The New Values to set the items at the beginning of List to.

The number of items in New Values determines the number of items that will be set at the beginning of List. One item means only the first item is set, two items means the first and second items are set etc.

The first item in List will be set to the first value in New Values; the second item in List will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List or New Values is null.

Remarks

Empty New Values

If New Values is empty (i.e. []) there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.7 - Set Items At End

Sets the items at the end of a List to new values.
Icon

Set Items At End

(Cortex.Blocks.Lists.SetItem.SetItemsAtEndBlock`2)

Description

Sets the items at the end of a List to New Values.

Examples

Set the items at the end of a List to New Values

This example will set the second last and last items at the end of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
New Values ($)NewValues, with value ["Some Modified Text", 10] ($)NewValues is a variable of type IEnumerable<dynamic>

Result

Setting the second last and last items at the end of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively, results in the variable ($)List being updated to the following:

["Some Text", 1, "Some Modified Text", 10]

Properties

List

The List to set the items in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Values

The New Values to set the items at the end of List to.

The number of items in New Values determines the number of items that will be set at the end of List. One item means only the last item is set, two items means the second last and last items are set etc.

The last item in List will be set to the last value in New Values; the second last item in List will be set to the second last value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyEmptyException Thrown when List contains no items.
PropertyNullException Thrown when List or New Values is null.

Remarks

Empty New Values

If New Values is empty (i.e. []) there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.8 - Set Items At Index

Sets the items at the specified index of a List to new values.
Icon

Set Items At Index

(Cortex.Blocks.Lists.SetItem.SetItemsAtIndexBlock`2)

Description

Sets the items at the specified Index of a List to New Values.

Examples

Set the Items at the first Index (i.e. 0) of a List to New Values

This example will set the 2 items starting at index 0 of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
New Values ($)NewValues, with value ["Some Modified Text", 10] ($)NewValues is a variable of type IEnumerable<dynamic>
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Setting the two items at index 0 of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", 10] respectively, results in the variable ($)List being updated to the following:

["Some Modified Text", 10, "Some More Text", 2]

Properties

List

The List to set the items in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Values

The New Values to set the items at the specified Index of List to.

The number of items in New Values determines the number of items that will be set at the end of List. One item means one item is set, two items means two items are set etc.

The item at Index of List will be set to the first value in New Values; the item at Index + 1 of List will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Index

The Index to start setting the items at. This is an inclusive index, which means the item at the specified index will be included.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
PropertyEmptyException Thrown when New Values contains no items.
PropertyNullException Thrown when List or New Values is null.
PropertyValueOutOfRangeException Thrown when Index is less than 0 or greater than the count of items in List - 1.
Thrown when Index + count of items in New Values is greater than the count of items in the List - 1.

Remarks

Index is inclusive

The Index is an inclusive index, which means the item at the index will be included in the set items.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.9 - Set Items At Indexes

Sets the items at each of the specified indexes of a List to new values.
Icon

Set Items At Indexes

(Cortex.Blocks.Lists.SetItem.SetItemsAtIndexesBlock`2)

Description

Sets the items at each of the specified Indexes of a List to New Values.

Examples

Sets items at the first and third Indexes (i.e. [0, 2]) of a List to New Values

This example will set items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", "Some More Modified Text"] respectively.

Properties

Property Value Notes
List ($)List, with value ["Some Text", 1, "Some More Text", 2] ($)List is a variable of type IList<dynamic>
New Values ($)NewValues, with value ["Some Modified Text", "Some More Modified Text"] ($)NewValues is a variable of type IEnumerable<String>
Indexes ($)Indexes, with value [0, 2] ($)Indexes is a variable of type IEnumerable<Int32>

Result

Setting items at indexes 0 and 2 of ["Some Text", 1, "Some More Text", 2] to ["Some Modified Text", "Some More Modified Text"] respectively, results in the variable ($)List being updated to the following:

["Some Modified Text", 1, "Some More Modified Text", 2]

Properties

List

The List to set the items in.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

New Values

The New Values to set the items at the specified Indexes of List to.

The number of items in New Values must match the number of items in Indexes.

The List item at the first index in Indexes will be set to the first value in New Values; the List item at the second index in Indexes will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Indexes

The Indexes of the items to set.

Valid values are between and including 0 and the total count of items in the List - 1.

For information about what an index is, please see Indexes.

Data Type IEnumerable<Int32>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<int>() {}

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
DuplicateValueException Thrown when Indexes contains duplicate values.
PropertyItemCountException Thrown when the count of items in New Values and the count of items in Indexes are not the same.
PropertyNullException Thrown when List or New Values or Indexes is null.
PropertyValueOutOfRangeException Thrown when Indexes contains no values.
Thrown when any index in Indexes is less than 0 or greater than the count of items in List - 1.

Remarks

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.10 - Set Items With Value

Sets all items matching a value in a List to a new value.
Icon

Set Items With Value

(Cortex.Blocks.Lists.SetItem.SetItemsWithValueBlock`2)

Description

Sets all items matching a Value in a List to a New Value.

Examples

Set all items matching a Value in a List to a New Value

This example will attempt to set all items matching the value 1 in [1, 2, 3, 3, 2, 1] to 10.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Value ($)Value, with value 1 ($)Value is a variable of type Int32
New Value ($)NewValue, with value 10 ($)NewValue is a variable of type Int32

Result

Attempting to set all items matching the value 1 in [1, 2, 3, 3, 2, 1] to 10 results in the variable ($)List being updated to the following:

[10, 2, 3, 3, 2, 10]

Properties

List

The List to set all matching items in.

Items are considered matching if they have the specified Value.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Value

The Value the items to set must match.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Value

The New Value to set all matching items in List to.

Data Type TItem
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
InvalidPropertyValueException Thrown when Value or New Value are null and List only accepts non-nullable value types. See Value Is Invalid.
PropertyNullException Thrown when List is null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []) there is nothing to set, so no operation is performed.

No items matching Value

If List does not contain items matching the specified Value, there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.12.7.11 - Set Items With Values

Sets all items matching one of the specified values in a List to new values.
Icon

Set Items With Values

(Cortex.Blocks.Lists.SetItem.SetItemsWithValuesBlock`2)

Description

Set all items matching one of the specified Values in a List to New Values.

Examples

Set all items matching one of the specified Values in a List to New Values

This example will attempt to set all items matching one of the values [1, 2] in [1, 2, 3, 3, 2, 1] to [10, 20] respectively.

Properties

Property Value Notes
List ($)List, with value [1, 2, 3, 3, 2, 1] ($)List is a variable of type IList<Int32>
Values ($)Values, with value [1, 2] ($)Values is a variable of type IEnumerable<Int32>
NewValues ($)NewValues, with value [10, 20] ($)NewValues is a variable of type IEnumerable<Int32>

Result

Attempting to set all items matching one of the values [1, 2] in [1, 2, 3, 3, 2, 1] to [10, 20] respectively, results in the variable ($)List being updated to the following:

[10, 20, 3, 3, 20, 10]

Properties

List

The List to set all matching items in.

Items are considered matching if they have one of the specified Values.

List can be any IList<TItem>, where TItem represents the type of items in the List.

Data Type IList<TItem>
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)List with no value

Values

The Values the items to set must match one of.

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

New Values

The New Values to set the items matching the corresponding Values in List to.

The number of items in New Values must match the number of items in Values.

List items matching the first value in Values will be set to the first value in New Values; List items matching the second value in Values will be set to the second value in New Values etc.

Data Type IEnumerable<TItem>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Exceptions

The exceptions thrown by the block can be found below:

Name Description
CannotModifyReadOnlyListException Thrown when List is read-only.
DuplicateValueException Thrown when Values contains duplicate values.
PropertyItemCountException Thrown when the count of items in Values and the count of items in New Values are not the same, or neither contain any items.
PropertyNullException Thrown when List or Values or New Values are null.

Remarks

Item Equality

For information and examples of how it is determined whether an item matches a specified value, please see Object Equality.

Empty List

If List is empty (i.e. []) there is nothing to set, so no operation is performed.

No items matching a specified value in Values

If List does not contain items matching one of the specified Values, there is nothing to set for that value.

No items matching Values

If List does not contain items matching any of the specified Values, there is nothing to set, so no operation is performed.

Defining lists using literal syntax

For information about how to define lists using literal syntax, see Create a List<TItem>.

Defining lists using expression syntax

For information about how to define lists using expression syntax, see Create a List<TItem>.

Lists containing items of a single data type vs multiple data types

For information about the different types of lists, including those that can contain only a single type of item, and those that can contain multiple types of item, see Lists.

6.3.13 - Logs

Blocks related to creating Logs.

6.3.13.1 - Log Event

Log events to the filesystem.

6.3.13.1.1 - Log Event

Logs an event to the filesystem.
Icon

Log Event

(Cortex.Blocks.Logs.LogEvent.LogEventBlock)

Description

Logs an event to the filesystem.

Additional options can be specified:

  • Event Type can be specified to define the type of event being logged.
  • Event Severity can be specified to define the severity of the event being logged.
  • Started At can be specified to define the Date and Time the event being logged started.
  • Ended At can be specified to define the Date and Time the event being logged ended.

Examples

Log an event

This example will log details about all tasks of a multi-stage process that provisions a new user at a company.

  • Process: "Provision New User"
    • Stage: "Configure Active Directory"
      • Task: "Add User to Azure Active Directory"
      • Task: "Add User to On-Premise Active Directory"
    • Stage: "Configure Email"
      • Task: "Create Outlook Account"
      • Task: "Create Default Signature"

Properties

Property Value Notes
Event Details ($)EventDetails, with value {"Process":{"Provision New User":{"Stages":[{"Configure Active Directory":{"Tasks":["Add User to Azure Active Directory","Add User to On-Premise Active Directory"]}},{"Configure Email":{"Tasks":["Create Outlook Account","Create Default Signature"]}}]}}} ($)EventDetails is a variable of type Structure.
Event Type ($)EventType, with value "User Provisioning" ($)EventType is a variable of type String.
Event Severity ($)EventSeverity, with value EventSeverity.Information ($)EventSeverity is a variable of type Nullable<EventSeverity>.
Started At ($)StartedAt, with value of DateTimeOffset that has a text representation of 2021-11-15T10:05:32.0000000Z ($)StartedAt is a variable of type Nullable<DateTimeOffset>.
Ended At ($)EndedAt, with value of DateTimeOffset that has a text representation of 2021-11-15T10:06:12.0000000Z ($)EndedAt is a variable of type Nullable<DateTimeOffset>.

Result

Logging the event results in the following log being written:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "@t":"2021-11-15T10:06:15.0000000Z",
    "@mt":"{@Event}",
    "Event":{
        "Type":"User Provisioning",
        "Duration":{
            "StartedAt":"2021-11-15T10:05:32.0000000Z",
            "EndedAt":"2021-11-15T10:06:12.0000000Z",
            "InMs":40000,
            "$type":"EventDurationDetails"
        },
        "Details":{
            "Process":{
                "Provision New User":{
                    "Stages":[
                        {
                            "Configure Active Directory":{
                                "Tasks":[
                                    "Add User to Azure Active Directory",
                                    "Add User to On-Premise Active Directory"
                                ]
                            }
                        },
                        {
                            "Configure Email":{
                                "Tasks":[
                                    "Create Outlook Account",
                                    "Create Default Signature"
                                ]
                            }
                        }
                    ]
                }
            },  
            "Correlation":{
                "TraceId":null,
                "SpanId":null,
                "ParentSpanId":null,
                "$type":"EventCorrelationDetails"
            },
            "Service":{
                "Type":null,
                "IpAddressOrFqdn":null,
                "$type":"ServiceDetails"
            },
            "$type":"StructuredEventLog"
        }
    }
}

For information about the format of the logs written, see Anatomy of a Log.

For information about where the logs are written to, see Configuring Logging.


Properties

Event Details

The Event Details to log.

Event Details can be any object of any data type; it does not have to be a String. Using a data type like a Structure allows you to create richer logs with a more defined format. This makes them easier to consume, process and query by other systems that consume logs, such as Grafana, ElasticSearch and Splunk, which are commonly used for log analysis, reporting and dashboarding.

Data Type dynamic
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)EventDetails with no value

Event Type

Event Type can be specified to define the type of event being logged.

Event Type is a free format text property. If left blank, null, or empty (i.e. "") it will default to Cortex.Blocks.Logs.LogEvent.LogEventBlock.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value No value (defaults to null)

Event Severity

Event Severity can be specified to define the severity of the event being logged.

Event Severity can be any of the following predefined values:

  • EventSeverity.Verbose - Logs that contain the most detailed messages. These messages may contain sensitive application data. These logs should never be enabled in a production environment.
  • EventSeverity.Debug - Logs that are used for interactive investigation during development. These logs should primarily contain information useful for debugging and have no long-term value.
  • EventSeverity.Information - Logs that track the general path of the flow execution. These logs should have long-term value.
  • EventSeverity.Warning - Logs that highlight an abnormal or unexpected event in the path of the flow execution, but do not otherwise cause the flow execution to exit.
  • EventSeverity.Error - Logs that highlight when the current flow execution exits due to an error. These should indicate a failure in the current flow execution, not a service-wide or process-wide failure.
  • EventSeverity.Fatal - Logs that describe an unrecoverable service or process error, or a catastrophic failure that requires immediate attention.

Event Severity can also be left blank or set to null, in which case it will default to EventSeverity.Information.

Logs with an Event Severity of EventSeverity.Information, have the event severity ommitted from the log that is written to the filesystem. This is to save disk space, as typically the highest volume of logs produced are Information logs. This cannot be changed and is a restriction of the underlying logging system used. All non-Information logs do include the event severity in the log that is written to the filesystem.

Data Type Nullable<EventSeverity>
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Information

Started At

Started At can be specified to define the Date and Time the event being logged started.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

If Started At is left blank or set to null, a value of null will be logged.

For more information about Date and Time, please see Working with Date and Time.

Data Type Nullable<DateTimeOffset>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value DateTimeOffset.UtcNow

Ended At

Ended At can be specified to define the Date and Time the event being logged ended.

Its text representation will be in the ISO 8601 Standard (e.g. 2021-11-05T08:48:08.0307614+00:00).

If Ended At is left blank or set to null, a value of null will be logged.

For more information about Date and Time, please see Working with Date and Time.

Data Type Nullable<DateTimeOffset>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value DateTimeOffset.UtcNow

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Event Severity is not one of the specified EventSeverity types (e.g. (EventSeverity)10).
PropertyNullException Thrown when Event Details is null.

Remarks

Configuring Logging

Log settings exist for the following Cortex Services:

Service Default File Location Description
Cortex Debugger Service <install-location>\appsettings.json Debugger Service is used to debug flows when developing them in Cortex Studio
Cortex Flow Execution Service <install-location>\appsettings.json Flow Execution Service is used to execute published flows in a runtime environment (e.g. Development, UAT, Production)

An example of the log settings can be found below (some settings that do not need to be modified have been ommitted):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "Cortex.Blocks.Logs": {
    "Using": [ "Serilog.Sinks.File" ],
    "MinimumLevel": {
      "Default": "Verbose"
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "%ProgramData%/Cortex/Logging/LogEventBlock-.json",
          "rollingInterval": "Day",
          "fileSizeLimitBytes": 50000000,
          "rollOnFileSizeLimit": true,
          "retainedFileCountLimit": 365
        }
      }
    ]
  }
}

A list of the main log settings (highlighted above) and an accompanying description can be found below:

Log Setting Default Value Description
Default "Verbose" The default minimum log level that will be logged.

Possible options are "Verbose", "Debug", "Information", "Warning", "Error", "Fatal".

The order of log levels is "Verbose"->"Debug"->"Information"->"Warning"->"Error"->"Fatal". When setting the default log level, that level and every level to its right will be logged.
path "%ProgramData%/Cortex/Logging/LogEventBlock-.json" The location that logs will be written to.

This value supports use of environment variables, as seen in the default value.

If any part of the location does not exist, the logging will attempt to create it.

The file names written will include a date format after the - and before .json (e.g. "LogEventBlock-yyyyMMdd.json" -> "LogEventBlock-20210921.json")

The date format used will be decided by the value specified in rollingInterval.

The file name may also include a file count number and is added automatically to make sure file names are unique. This can happen if rollOnFileSizeLimit is set to true and a log file reaches the size specified in fileSizeLimitBytes. It can also happen if the log file is locked by another process, preventing it from being written to.
rollingInterval "Day" The time interval at which the logging system will create and start logging to a new log file.

Possible options are "Infinite", "Year", "Month", "Day", "Hour", "Minute".

Infinite means that the log files never roll over based on a time interval.
fileSizeLimitBytes 50000000 The maximum file size in bytes that the loggging system will write to. Once this size is exceeded the logging system will create and start logging to a new log file.

Null can be used to mean unlimited size.

rollOnFileSizeLimit must be set to true for this setting to take effect.
rollOnFileSizeLimit true Whether the loggging system should start creating a new log file if the current one reaches the maximum file size specified in fileSizeLimitBytes.

Possible options are true and false.
retainedFileCountLimit 365 The maximum number of files to retain on disk. Once this number is reached, the loggging system will start delete the oldest file.

Please note that if the appsetting.json file cannot be found for one of the services, the logger will use the same default settings specified above.

Anatomy of a Log

The format of the logs written by this block are the same as the logs written by the rest of the Cortex Services. This is to ensure logging is consistent and done one way within Cortex. Hopefully this will make it easier to work with logging, and also make it easier to gain a holistic picture into what has happened to a flow execution throughout its entire lifecycle (i.e. from initial request to returning the response to the caller), rather than just what happens inside of the flow.

An example log can be found below:

{
    "@t":"2021-11-15T10:06:15.0000000Z",
    "@mt":"{@Event}",
    "@l":"Debug",
    "Event":{
        "Type":"User Provisioning",
        "Duration":{
            "StartedAt":"2021-11-15T10:05:32.0000000Z",
            "EndedAt":"2021-11-15T10:06:12.0000000Z",
            "InMs":40000,
            "$type":"EventDurationDetails"
        },
        "Details":{
            "Process":{
                "Provision New User":{
                    "Stages":[
                        {
                            "Configure Active Directory":{
                                "Tasks":[
                                    "Add User to Azure Active Directory",
                                    "Add User to On-Premise Active Directory"
                                ]
                            }
                        },
                        {
                            "Configure Email":{
                                "Tasks":[
                                    "Create Outlook Account",
                                    "Create Default Signature"
                                ]
                            }
                        }
                    ]
                }
            }
        },  
        "Correlation":{
            "TraceId":null,
            "SpanId":null,
            "ParentSpanId":null,
            "$type":"EventCorrelationDetails"
        },
        "Service":{
            "Type":null,
            "IpAddressOrFqdn":null,
            "$type":"ServiceDetails"
        },
        "$type":"StructuredEventLog"
        }
    }
}

A list of each of the log’s properties and an accompanying description can be found below:

Log Property Description
@t The date and time the log was written. The format is ISO 8601 Standard.
@mt The message template for the log. This is set to log the entire Event.
@l The level for the log. The value of Event Severity is used here.
Event The event that was logged.
Event.Type The type of event that was logged. This can be used for log analysis and reporting. The value of Event Type is used here.
Event.Duration Contains the date and time the event started at, ended at, and its duration.
Event.Duration.StartedAt The date and time the event started. The format is ISO 8601 Standard. The value of Started At is used here.
Event.Duration.EndedAt The date and time the event ended. The format is ISO 8601 Standard. The value of Ended At is used here.
Event.Duration.InMs The duration of the event in milliseconds and is calculated using Event.Duration.StartedAt and Event.Duration.EndedAt .
Event.Duration.$type The .Net data type used to represent the duration data. This can be ignored and is an artefact of the underlying implementation.
Event.Details Contains the details of the event. The value of Event Details is written as a child property of this (e.g. in this example Event.Details.Process).
Event.Correlation Contains details that can be used to correlate related events. E.g. The act of starting a new flow execution may result in multiple Cortex Services processing the event. As a result, each service may write its own logs, and additionally the flow developer may also write out multiple logs during the flow execution. The Correlation details allow all of these logs to easily be correlated back together when performing log analysis and reporting to gain a full picture of everything that happened.
Event.Correlation.TraceId ID common to all related logs, so they can be easily correlated together.
Event.Correlation.SpanId Unique ID for each log, so tools like Grafana can display a call stack, showing each step that occurred when processing an event.
Event.Correlation.ParentSpanId The ID of the step that called this step of processing, so tools like Grafana can display a call stack, showing each step that occurred when processing an event.
Event.Correlation.$type The .Net data type used to represent the correlation data. This can be ignored and is an artefact of the underlying implementation.
Event.Service Contains details of the Cortex Service that logged this event, and will allow enhanced log analysis and reporting to gain a full picture of everything that happened.
Event.Service.Type The type of the Cortex Service that logged this event.
Event.Service.IpAddressOrFqdn The IP address or fully qualified domain name of the Cortex Service that logged this event.
Event.Service.$type The .Net data type used to represent the service data. This can be ignored and is an artefact of the underlying implementation.
Event.$type The .Net data type used to represent the event data. This can be ignored and is an artefact of the underlying implementation.

Null or Empty Event Type

If Event Type is left blank, null, or empty (i.e. "") it will default to Cortex.Blocks.Logs.LogEvent.LogEventBlock.

Null Event Severity

If Event Severity is left blank or set to null, it will default to EventSeverity.Information.

Null Started At

If Started At is left blank or set to null, a value of null will be logged.

Null Ended At

If Ended At is left blank or set to null, a value of null will be logged.

6.3.14 - Loops

Blocks used to perform looping.

6.3.14.1 - For Each Loop

Blocks used to loop through the items in a collection (i.e. Lists, Dictionaries and Structures).

6.3.14.1.1 - For Each Loop

Loops through all items in the specified collection (i.e. Lists, Dictionaries and Structures).
Icon

For Each Loop

(Cortex.Blocks.Loops.ForEach.ForEachLoopBlock)

Description

Loops through all items in the specified Collection (i.e. Lists, Dictionaries and Structures).

The "Index" and "Value" of the current item are returned as properties of a Structure, which is saved to the Current Iteration.

Examples

Loop through all items in a list

This example will loop through all items in ["Item1", "Item2", "Item3"].

Properties

Property Value Notes
Collection ($)Collection, with value ["Item1", "Item2", "Item3"] ($)Collection is a variable of type IList<String>
Current Iteration ($)CurrentIteration, with no value ($)CurrentIteration is a variable of type Structure

Result

Looping through all items in ["Item1", "Item2", "Item3"] will result in 3 loops with ($)CurrentIteration being updated to the following:

1st loop

{
    "Index": 0,
    "Value": "Item1"
}

2nd loop

{
    "Index": 1,
    "Value": "Item2"
}

3rd loop

{
    "Index": 2,
    "Value": "Item3"
}

Loop through all items in a dictionary or structure

This example will loop through all items in {"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"}.

Properties

Property Value Notes
Collection ($)Collection, with value {"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"} ($)Collection is a variable of type IDictionary<String, String> or Structure
Current Iteration ($)CurrentIteration, with no value ($)CurrentIteration is a variable of type Structure

Result

Looping through all items in {"Key1": "Value1", "Key2": "Value2", "Key3": "Value3"} will result in 3 loops with ($)CurrentIteration being updated to the following:

1st loop

{
    "Index": 0,
    "Value": {
        "Key": "Key1",
        "Value": "Value1"
    }
}

2nd loop

{
    "Index": 1,
    "Value": {
        "Key": "Key2",
        "Value": "Value2"
    }
}

3rd loop

{
    "Index": 2,
    "Value": {
        "Key": "Key3",
        "Value": "Value3"
    }
}

Properties

Collection

The Collection to loop through.

If Collection is empty (i.e. contains no items), no looping will occur.

Data Type IEnumerable
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Collection with no value

Current Iteration

The Current Iteration the looping is at.

Current Iteration is set to a Structure on each loop, containing the current item’s "Index" and "Value". "Index" is set to 0 on the first loop, and on each subsequent loop is incremented by 1.

Looping will continue whilst "Index" is less than the number of items in Collection, with the flow execution exiting via the block’s right port (blue loop icon).

Once "Index" equals the number of items in Collection, looping stops, the flow execution exits via the block’s bottom port (green tick) and Current Iteration is reset to an empty Structure.

If Current Iteration "Index" is modified during a loop, it will automatically be set back to its original value immediately before the next loop begins.

Data Type Structure
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)CurrentIteration with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Collection is null.

Remarks

Empty Collection

If Collection is empty (i.e. contains no items), no looping will occur.

6.3.14.2 - For Loop

Blocks used to loop a specified number of times.

6.3.14.2.1 - For Loop

Loops a specified number of times based on a given start index, end index and increment.
Icon

For Loop

(Cortex.Blocks.Loops.For.ForLoopBlock)

Description

Loops a specified number of times based on a given Start Index, End Index and Increment.

Examples

Loop between 0 and 2 incrementing by 1

This example will loop between 0 and 2 incrementing by 1 each loop.

Properties

Property Value Notes
Start Index ($)StartIndex, with value 0 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 2 ($)EndIndex is a variable of type Int32
Increment ($)Increment, with value 1 ($)Increment is a variable of type Int32
Current Index ($)CurrentIndex, with value 0 ($)CurrentIndex is a variable of type Int32 that will be incremented by ($)Increment each loop

Result

Looping between 0 and 2 incrementing by 1 each loop will result in 3 loops with ($)CurrentIndex being updated to the following:

1st loop

0

2nd loop

1

3rd loop

2

Loop between 10 and 20 incrementing by 5

This example will loop between 10 and 20 incrementing by 5 each loop.

Properties

Property Value Notes
Start Index ($)StartIndex, with value 10 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 20 ($)EndIndex is a variable of type Int32
Increment ($)Increment, with value 5 ($)Increment is a variable of type Int32
Current Index ($)CurrentIndex, with value 0 ($)CurrentIndex is a variable of type Int32 that will be incremented by ($)Increment each loop

Result

Looping between 10 and 20 incrementing by 5 each loop will result in 3 loops with ($)CurrentIndex being updated to the following:

1st loop

10

2nd loop

15

3rd loop

20

Loop between 20 and 10 incrementing by -5

This example will loop between 20 and 10 incrementing by -5 each loop.

Properties

Property Value Notes
Start Index ($)StartIndex, with value 20 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 10 ($)EndIndex is a variable of type Int32
Increment ($)Increment, with value -5 ($)Increment is a variable of type Int32
Current Index ($)CurrentIndex, with value 0 ($)CurrentIndex is a variable of type Int32 that will be incremented by ($)Increment each loop

Result

Looping between 20 and 10 incrementing by -5 each loop will result in 3 loops with ($)CurrentIndex being updated to the following:

1st loop

20

2nd loop

15

3rd loop

10

Properties

Start Index

The Start Index the looping will start at. This is an inclusive index, which means the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

End Index

The End Index the looping will end at. This is an inclusive index, which means the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Increment

The Increment to be added to Current Index every time the block loops.

Increment can be:

If any of the above are not true or Increment is 0 then an InfiniteLoopException will be thrown the first time a flow execution executes this block.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Current Index

The Current Index the looping is at.

Current Index initially gets set to the value of Start Index on the first loop, and on each subsequent loop is incremented by the value of Increment.

If Increment is a positive value, the block will continue looping whilst Current Index is less than End Index; with the flow execution exiting via the block’s right port (blue loop icon).

If Increment is a negative value, the block will continue looping whilst Current Index is greater than Start Index; with the flow execution exiting via the block’s right port (blue loop icon).

When either of the above are not true the block stops looping, the flow execution exits via the block’s bottom port (green tick) and Current Index is reset to 0

At this moment, there is a known limitation with Current Index, which requires the variable used must have an Int32 value assigned to it before the block executes. If it does not then an InvalidPropertyValueException will be thrown the first time a flow execution executes this block.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)CurrentIndex with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InfiniteLoopException Thrown when Increment is 0. See Increment Is Zero.
Thrown when Increment has a positive value and Start Index is greater than End Index. See Increment Is Positive.
Thrown when Increment has a negative value and Start Index is less than End Index. See Increment Is Negative.
InvalidPropertyValueException Thrown when Current Index does not have an Int32 value assigned to it before the block executes. See Value Is Invalid.

Remarks

Start Index and End Index are inclusive

The Start Index and End Index properties are both inclusive indexes, which means those indexes will be included in the looping range (e.g. if Start Index is 0 and End Index is 1, the block will loop 2 times).

Start Index greater than End Index

Start Index can be greater than End Index. If this is the case, Increment must be a negative value. See Example above.

Known Limitations

The variable used for Current Index must have an Int32 value assigned to it before the block executes. If it does not then an InvalidPropertyValueException will be thrown the first time a flow execution executes this block.

6.3.15 - Microsoft365

Blocks related to working with Microsoft365.

6.3.15.1 - Outlook

Blocks related to working with Outlook.

6.3.15.1.1 - Send Email

Blocks related to sending Emails.

6.3.15.1.1.1 - Send Email Using Microsoft 365

Sends an email using the SMTP server hosted by Outlook.
Icon

Send Email Using Microsoft 365

(Cortex.Blocks.Microsoft365.Outlook.SendEmail.SendEmailUsingMicrosoft365Block)

Description

Connects to the SMTP server hosted by Outlook using the specified Credentials, and sends an Email Message.

This block only supports authentication via OAuth (using Microsoft365OAuthCredentials or Microsoft365OAuthCertificateCredentials), to send an email using basic authentication, see Send Email Using SMTP Server.

Examples

Sending an email using client credentials

This example will send an email from sender@outlook.com to recipient@outlook.com using the SMTP server hosted by Outlook.

The OAuth mechanism in this example uses client credentials. Therefore, for this example to work correctly, the Credentials provided must be a Microsoft365OAuthCredentials.

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Credentials ($)Credentials with value {"ClientId": "clientId", "ClientSecret": "encryptedClientSecret", "TenantId": "tenantId", ObjectId: "objectId"}

In this example ($)Credentials has been set up using the following Expression:

new Microsoft365OAuthCredentials(clientId: "clientId", clientSecret: "encryptedClientSecret", tenantId: "tenantId", objectId: "objectId")
($)Credentials is a variable of type Microsoft365OAuthCredentials

The ClientSecret property in the Microsoft365OAuthCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.

Result

An email with Normal priority is sent from sender@outlook.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the connection is closed.


Sending an email using certificate credentials

This example will send an email from sender@outlook.com to recipient@outlook.com using the SMTP server hosted by Outlook.

The OAuth mechanism in this example uses certificate credentials. Therefore, for this example to work correctly:

For more information on:

Properties

Property Value Notes
Email Message ($)EmailMessage with value {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []}

In this example ($)EmailMessage has been set up using the following Expression:

new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null)
($)EmailMessage is a variable of type EmailMessage

As Priority and BodyFormat are null, the email will be sent with a Text body and Normal priority.
Credentials ($)Credentials with value {"CertificatePath": "C:\\certificate.pfx", "CertificatePassword": "encryptedPassword", "ClientId": "clientId", "TenantId": "tenantId", "ObjectId": "objectId"}

In this example ($)Credentials has been set up using the following Expression:

new Microsoft365OAuthCertificateCredentials(certificatePath: @"C:\certificate.pfx", certificatePassword: "encryptedPassword", clientId: "clientId", tenantId: "tenantId", objectId: "objectId")
($)Credentials is a variable of type Microsoft365OAuthCertificateCredentials

The CertificatePassword property in the Microsoft365OAuthCertificateCredentials must be encrypted, for more information on how to encrypt the password, see EncryptedText.

Result

An email with Normal priority is sent from sender@outlook.com to recipient@outlook.com with a subject of "Example email subject" and a Text body of "Example email body", and then the connection is closed.


Properties

Email Message

The Email Message to send via the SMTP server hosted by Outlook. This property contains all of the information in relation to the email to be sent, these are:

Note that if the properties Priority and BodyFormat are set to null when creating an EmailMessage using a constructor, the email will be sent with Normal priority and with a Text body.

For more detailed information on each of the properties, see EmailMessage.

Data Type EmailMessage
Property Type Input
Is Advanced false
Default Editor Literal
Default Value EmailMessage with value shown below:
{
  "To": [
    {
      "Name": null,
      "Address": ""
    }
  ],
  "From": {
    "Name": "",
    "Address": ""
  },
  "Cc": [],
  "Bcc": [],
  "Priority": "EmailMessagePriority.Normal",
  "Subject": "",
  "BodyFormat": "EmailMessageBodyFormat.Text",
  "Body": "",
  "Attachments": []
}

Credentials

The Credentials object that includes all of the information required to connect to an SMTP server hosted by Outlook. There are two data types that can be used, which depends on the desired OAuth mechanism:

Note that the Send Email Using Microsoft 365 block automatically handles retrieval of access tokens using the following rules:

  • If an access token does not exist, a new access token will be retrieved and used when the block runs.
  • If an access token already exists but is expired, a new access token will be retrieved and used when the block runs.
  • If an access token already exists and is valid, it will be used when the block runs.

It is recommended to use a Variable for Credentials when it will be used across multiple Send Email Using Microsoft 365 blocks, as using a variable will allow for reuse of the same access token. Using a Literal to set the Credentials will cause the access token to only be used once and a new acccess token will be requested for every Send Email Using Microsoft 365 block.

Data Type Microsoft365Credentials
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Microsoft365OAuthCredentials with value shown below:
{
  "ClientId": "",
  "ClientSecret": "",
  "TenantId": "",
  "ObjectId": "",
}

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when BodyFormat within the Email Message is not one of the specified EmailMessageBodyFormat values (e.g. (EmailMessageBodyFormat)10).
Thrown when Priority within the Email Message is not one of the specified EmailMessagePriority values (e.g. (EmailMessagePriority)10).
CryptographicException Thrown when an incorrect CertificatePath is provided within Microsoft365OAuthCertificateCredentials.
Thrown when an incorrect CertificatePassword is provided within Microsoft365OAuthCertificateCredentials.
FileNotFoundException Thrown when a non-existent file path is provided in Attachments within Email Message.
IOException Thrown when the desired socket is held by another process; re-running the flow typically solves this.
MsalServiceException Thrown when an invalid ClientId is provided within Microsoft365OAuthCredentials.
Thrown when an invalid ClientSecret is provided within Microsoft365OAuthCredentials.
Thrown when an invalid TenantId is provided within Microsoft365OAuthCredentials.
Thrown when an invalid ClientId is provided within Microsoft365OAuthCertificateCredentials.
Thrown when an invalid TenantId is provided within Microsoft365OAuthCertificateCredentials.
PropertyNullException Thrown when the Email Message is null.
Thrown when the To within Email Message is null.
Thrown when the From within Email Message is null.
Thrown when the Address in an EmailAddress within Email Message is null.
Thrown when the Credentials is null.
Thrown when the ClientId within Microsoft365OAuthCredentials is null.
Thrown when the ClientSecret within Microsoft365OAuthCredentials is null.
Thrown when the TenantId within Microsoft365OAuthCredentials is null.
Thrown when the ObjectId within Microsoft365OAuthCredentials is null.
Thrown when the CertificatePath within Microsoft365OAuthCertificateCredentials is null.
Thrown when the CertificatePassword within Microsoft365OAuthCertificateCredentials is null.
Thrown when the ClientId within Microsoft365OAuthCertificateCredentials is null.
Thrown when the TenantId within Microsoft365OAuthCertificateCredentials is null.
Thrown when the ObjectId within Microsoft365OAuthCertificateCredentials is null.
PropertyEmptyException Thrown when the To within Email Message is empty (i.e. []).
Thrown when the Address in an EmailAddress within Email Message is empty (i.e. "").
Thrown when the ClientId within Microsoft365OAuthCredentials is empty (i.e. "").
Thrown when the ClientSecret within Microsoft365OAuthCredentials is empty (i.e. "").
Thrown when the TenantId within Microsoft365OAuthCredentials is empty (i.e. "").
Thrown when the ObjectId within Microsoft365OAuthCredentials is empty (i.e. "").
Thrown when the CertificatePath within Microsoft365OAuthCertificateCredentials is empty (i.e. "").
Thrown when the CertificatePassword within Microsoft365OAuthCertificateCredentials is empty (i.e. "").
Thrown when the ClientId within Microsoft365OAuthCertificateCredentials is empty (i.e. "").
Thrown when the TenantId within Microsoft365OAuthCertificateCredentials is empty (i.e. "").
Thrown when the ObjectId within Microsoft365OAuthCertificateCredentials is empty (i.e. "").
ServiceException Thrown when an invalid ObjectId is provided within Microsoft365OAuthCredentials.
Thrown when an invalid ObjectId is provided within Microsoft365OAuthCertificateCredentials.
Thrown when trying to send an email as a user that the client application does not have rights to send as.
Thrown when the Address in an EmailAddress within Email Message is not of the correct format (RFC 5321).
UnauthorizedAccessException Thrown when access is denied to a file provided in Attachments within Email Message.

Remarks

Known Limitations

None

6.3.16 - Objects

Blocks common to all object data types.

6.3.16.1 - Convert Object

Convert an object to other data types.

6.3.16.1.1 - Convert Object To Text

Converts an object to text by replacing all {Property} format parameters in a specified format template with the Object’s corresponding property value.
Icon

Convert Object To Text

(Cortex.Blocks.Object.ConvertObject.ConvertObjectToTextBlock`1)

Description

Converts the given Object to Text.

It does this by replacing all {Property} format parameters in the specified Format Template with the corresponding property value from the given Object.

An additional Format Provider option can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting).

Examples

Convert Structure to Text

This example will convert:

{
    "LastPaymentAmount": 99.99, 
    "PercentagePaidOff": 0.8000, 
    "PercentageRemaining": 0.2000, 
    "TotalPaidOff": 350.99, 
    "TotalRemaining": 40
}

to text, based on the following format template:

"Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding."

The format parameter {LastPaymentAmount:C2} will display the 99.99 as U.S currency to two decimal places (i.e. $99.99):

  • LastPaymentAmount - is replaced by the value of the "LastPaymentAmount" property (i.e. 99.99).
  • C - indicates to include the currency symbol for the specified culture (i.e. $).
  • 2 - indicates to format the value to two decimal places.

The format parameter {PercentagePaidOff:P0} will display the 0.8000 as a percentage to zero decimal places (i.e. 80 %):

  • PercentagePaidOff - is replaced by the value of the "PercentagePaidOff" (i.e. 0.8000).
  • P - indicates the value should be formatted as a percentage.
  • 0 - indicates to format the percentage value to zero decimal places.

The format parameter {TotalRemaining:C2} will display the 40 as U.S currency to two decimal places (i.e. $40.00):

  • TotalRemaining - is replaced by the value of the "TotalRemaining" property (i.e. 40).
  • C - indicates to include the currency symbol for the specified culture (i.e. $).
  • 2 - indicates to format the value to two decimal places.

For information about format templates and parameters, please see Text Formatting.

Properties

Property Value Notes
Object ($)Object, with value {"LastPaymentAmount":99.99, "PercentagePaidOff":0.8000, "PercentageRemaining":0.2000, "TotalPaidOff":350.99, "TotalRemaining":40} ($)Object is a variable of type Structure
Format Template ($)FormatTemplate, with value "Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding." ($)FormatTemplate is a variable of type String
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Converting:

{
    "LastPaymentAmount": 99.99, 
    "PercentagePaidOff": 0.8000, 
    "PercentageRemaining": 0.2000, 
    "TotalPaidOff": 350.99, 
    "TotalRemaining": 40
}

to text, based on the following format template:

"Your latest payment of {LastPaymentAmount:C2} has been received. You have paid {PercentagePaidOff:P0} of your total and have {TotalRemaining:C2} outstanding."

results in the variable ($)Text being updated to the following:

"Your latest payment of $99.99 has been received. You have paid 80 % of your total and have $40.00 outstanding."

Properties

Object

The Object to convert to Text.

All {Property} format parameters which match a property name in the Object will be replaced by that property’s value.

The values of matching properties do not have to be text, they can be any data type. Any non-text value will be converted to its text representation when it is replaced.

For information about how types are converted to their text representation please see Converting Objects To Text.

Data Type TObject
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Object with no value

Format Template

Format Template can be specified to define the format of the resultant Text.

All {Property} format parameters in Format Template will be replaced with the corresponding property value from the Object.

{Property} format parameters are case-sensitive, so must exactly match the property name in the Object; those that do not will not be replaced.

If Format Template is specified but does not contain any {Property} format parameters, nothing is replaced; Text will be set to the value of Format Template.

If Format Template is not specified, null or empty (i.e. ""), Text will be set to the value of Convert.ToString(Object, Format Provider).

For information about format templates and parameters, please see Text Formatting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Format Provider

Format Provider can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting.).

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Data Type IFormatProvider
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Text

The formatted Text that results from replacing all {Property} format parameters in Format Template with their corresponding property value from the given Object.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
FormatException Thrown when Format Template contains a format parameter that is invalid or not well-formed (e.g. "Cost is {TotalCost:Q2}, as "Q" is not a valid format parameter).
PropertyNullException Thrown when Object is null.

Remarks

Text Formatting

Please note that changes to operating system settings, could result in some of the examples above displaying different results.

For information about format templates and parameters, please see Text Formatting.

Null or Empty Format Template

If Format Template is specified but does not contain any {Property} format parameters, nothing is replaced; Text will be set to the value of Format Template.

If Format Template is not specified, null or empty (i.e. ""), Text will be set to the value of Convert.ToString(Object, Format Provider).

Null Format Provider

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Nested Properties

Format parameters support nested properties, which means given an object like the following:

{
    "LastPaymentAmount": 99.99, 
    "PaidOff": { 
        "Percentage": 0.8000, 
        "Total": 350.99
    },
    "Remaining": {
        "Remaining": 0.2000, 
        "Total": 40
    }
}

that nested property values such as PaidOff.Total can be accessed. This is done by using the following format parameter syntax:

"{PaidOff.Total}"

Known Limitations

Currently the block does not support indexing into properties (i.e. ListProperty[0] or DictionaryProperty["key"]).

6.3.16.2 - Copy Object

Copy an object.

6.3.16.2.1 - Copy Object

Copies an Object.
Icon

Copy Object

(Cortex.Blocks.Objects.CopyObject.CopyObjectBlock`1)

Description

Makes a Copy of an Object.

Any type of object can be copied, including Lists, Dictionaries, Structures etc.

A deep copy will be performed, which means if the Object contains other objects, they are also copied. This is as opposed to a shallow copy, which only makes a copy of the Object; in a shallow copy contained objects are not copied, they are left as the original.

Examples

Copy a List

This example will make a copy of [[1, 2, 3], [4, 5, 6]].

Properties

Property Value Notes
Object ($)Object, with value [[1, 2, 3], [4, 5, 6]] ($)Object is a variable of type List<List<Int32>>
Copy ($)Copy, with no value ($)Copy is a variable that will be set to the type of the item (i.e. List<List<Int32>>)

Result

Making a copy of [[1, 2, 3], [4, 5, 6]] results in the variable ($)Copy being updated to the following:

[
    [
        1, 
        2, 
        3
    ], 
    [
        4, 
        5, 
        6
    ]
]

Note that ($)Copy is an exact copy. If ($)Copy has new items added to it, items updated in it, or items removed from it, the original that ($)Copy was copied from will not be affected.


Properties

Object

The Object to make the Copy of.

Any type of object can be copied, including Lists, Dictionaries, Structures etc.

A deep copy will be performed, which means if the Object contains other objects, they are also copied. This is as opposed to a shallow copy, which only makes a copy of the Object; in a shallow copy contained objects are not copied, they are left as the original.

Data Type TObject
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Object with no value

Copy

The Copy of the Object.

Data Type TObject
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Copy with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Null Object

If Object is not provided or is set to null, Copy will be set to null.

6.3.17 - PowerShell

Blocks related to working with Windows PowerShell and PowerShell Core.

6.3.17.1 - Execute PowerShell Script

Blocks related to executing PowerShell scripts with Windows PowerShell and PowerShell Core.

6.3.17.1.1 - Execute PowerShell Script

Executes a PowerShell script on the specified host.
Icon

Execute PowerShell Script

(Cortex.Blocks.PowerShell.ExecutePowerShellScript.ExecutePowerShellScriptBlock`1)

Description

Connects to a host using the specified PowerShell Session Details, and executes a Script, returning the Outputs and Records.

Close Session can be specified to choose whether the session on the host is closed or is kept open for use on subsequent Execute PowerShell Script blocks.

Examples

Execute a Script using PowerShellWinRMSessionDetails

This example will execute a script on the server with the following details:

  • Host - "host.domain.com"
  • Port - 5986
  • UseSsl - true

The host can be connected to with the following credentials:

  • Domain - "domain.com"
  • Username - "username"
  • Password - "password"

The server that the script will be executed on contains a text file in the following location C:\Folder\Example.txt, the file contains the following text before the script is executed:

"This is the content of the file located on the host the script is running on."

Properties

Property Value Notes
Script ($)Script with value "Get-Content \"C:\\Folder\\Example.txt\"" ($)Script is a variable of type String
Parameters ($)Parameters with no value ($)Parameters is a variable of type Dictionary<String, dynamic>
PowerShell Session Details ($)PowerShellSessionDetails with value {"ServerDetails": {"Host": "host.domain.com", "Port": 5986, "UseSsl": "true"}, "Credentials": {"Domain": "domain.com", "Username": "username", "Password": "encryptedPassword"}}

In this example ($)PowerShellSessionDetails has been set up using the following Expression:

new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))
($)Credentials is a variable of type PowerShellWinRMSessionDetails

The Password property within UserCredentials of the PowerShellWinRMSessionDetails must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession, with value true ($)CloseSession is a variable of type Boolean
Outputs ($)Outputs, with no value ($)Outputs will be set to the type IList<dynamic>
Records ($)Records, with no value ($)Records will be set to the type Records

Result

Running the Script results in the variable ($)Outputs being updated to the following:

[
    "This is the content of the file located on the host the script is running on."
]

It also results in the variable ($)Records being updated to the following:

{
    "ErrorRecords": [],
    "WarningRecords": [],
    "DebugRecords": [],
    "ProgressRecords": [],
    "VerboseRecords": [],
    "InformationRecords": []
}

After the Script has been executed, the session will be closed, for more information see Closing Sessions.


Execute a Script with Parameters using PowerShellWinRMSessionDetails

This example will execute a script on the server with the following details:

  • Host - "host.domain.com"
  • Port - 5986
  • UseSsl - true

The host can be connected to with the following credentials:

  • Domain - "domain.com"
  • Username - "username"
  • Password - "password"

The server that the script will be executed on contains a text file in the following location C:\Folder\Example.txt, the file contains the following text before the script is executed:

"This is the content of the file located on the host the script is running on."

In this example assume the following variables have been set before the script has been executed:

  • ($)FilePath with the value "Get-Content \"C:\\Folder\\Example.txt\""

Properties

Property Value Notes
Script ($)Script with value "Get-Content $FilePath" ($)Script is a variable of type String
Parameters ($)Parameters with value {"FilePath": ($)FilePath"} ($)Parameters is a variable of type Dictionary<String, dynamic>
PowerShell Session Details ($)PowerShellSessionDetails with value {"ServerDetails": {"Host": "host.domain.com", "Port": 5986, "UseSsl": "true"}, "Credentials": {"Domain": "domain.com", "Username": "username", "Password": "encryptedPassword"}}

In this example ($)PowerShellSessionDetails has been set up using the following Expression:

new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))
($)Credentials is a variable of type PowerShellWinRMSessionDetails

The Password property within UserCredentials of the PowerShellWinRMSessionDetails must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession, with value true ($)CloseSession is a variable of type Boolean
Outputs ($)Outputs, with no value ($)Outputs will be set to the type IList<dynamic>
Records ($)Records, with no value ($)Records will be set to the type Records

Result

Running the Script results in the variable ($)Outputs being updated to the following:

[
    "This is the content of the file located on the host the script is running on."
]

It also results in the variable ($)Records being updated to the following:

{
    "ErrorRecords": [],
    "WarningRecords": [],
    "DebugRecords": [],
    "ProgressRecords": [],
    "VerboseRecords": [],
    "InformationRecords": []
}

After the Script has been executed, the session will be closed, for more information see Closing Sessions.


Execute a Script that returns Records using PowerShellWinRMSessionDetails

This example will execute a script on the server with the following details:

  • Host - "host.domain.com"
  • Port - 5986
  • UseSsl - true

The host can be connected to with the following credentials:

  • Domain - "domain.com"
  • Username - "username"
  • Password - "password"

The server that the script will be executed on contains a text file in the following location C:\Folder\Example.txt, the file contains the following text before the script is executed:

"This is the content of the file located on the host the script is running on."

Properties

Property Value Notes
Script ($)Script with value $@"Get-Content \"C:\\Folder\\Example.txt\"; $DebugPreference = 'Continue'; Write-Warning 'Warning'; Write-Debug 'Debug'; Write-Information 'Information'; Write-Verbose 'Verbose' -Verbose; Get-Error" ($)Script is a variable of type String
Parameters ($)Parameters with no value ($)Parameters is a variable of type Dictionary<String, dynamic>
PowerShell Session Details ($)PowerShellSessionDetails with value {"ServerDetails": {"Host": "host.domain.com", "Port": 5986, "UseSsl": "true"}, "Credentials": {"Domain": "domain.com", "Username": "username", "Password": "encryptedPassword"}}

In this example ($)PowerShellSessionDetails has been set up using the following Expression:

new PowerShellWinRMSessionDetails(serverDetails: new ServerDetails("host.domain.com", 5986, true), credentials: new UserCredentials("domain.com", "username", "encryptedPassword"))
($)Credentials is a variable of type PowerShellWinRMSessionDetails

The Password property within UserCredentials of the PowerShellWinRMSessionDetails must be encrypted, for more information on how to encrypt the password, see EncryptedText.
Close Session ($)CloseSession, with value true ($)CloseSession is a variable of type Boolean
Outputs ($)Outputs, with no value ($)Outputs will be set to the type IList<dynamic>
Records ($)Records, with no value ($)Records will be set to the type Records

Result

Running the Script results in the variable ($)Outputs being updated to the following:

[
    "This is the content of the file located on the host the script is running on."
]

It also results in the variable ($)Records being updated to the following:

{
    "ErrorRecords": [
        "The term 'Get-Error' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again."
    ],
    "WarningRecords": [
        "Warning"
    ],
    "DebugRecords": [
        "Debug"
    ],
    "ProgressRecords": [
        "parent = -1 id = 0 act = Preparing modules for first use. stat =   cur =  pct = -1 sec = -1 type = Completed"
    ],
    "VerboseRecords": [
        "Verbose"
    ],
    "InformationRecords": [
        "Information"
    ]
}

After the Script has been executed, the session will be closed, for more information see Closing Sessions.


Properties

Script

The Script which will be executed on the Host provided within the PowerShell Session Details, this can be a script, a file path of a script on the host, or a cmdlet.

Note that to execute a script using its file path, the file path must accessible to the Host.

Data Type EncryptableText
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Parameters

The parameters to be passed into the Script.

Data Type IDictionary<String, dynamic>
Property Type Input
Is Advanced true
Default Editor Expression
Default Value No value (defaults to null)

PowerShell Session Details

The PowerShell Session Details object that includes all of the information required to connect and maintain a PowerShell Session. This property contains all of the information in relation to the server the script will be executed on, these are:

Data Type PowerShellSessionDetails
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)PowerShellSessionDetails with no value

Close Session

Close Session can be specified to choose whether the session on the Host is closed or is kept open for use on subsequent Execute PowerShell Script blocks, this defaults to false if left blank, please see Closing Sessions for more information.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Outputs

IList<dynamic> of outputs from the execution of the Script.

Data Type IList<dynamic>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Outputs with no value

Records

The Records object that includes the error, warning, debug, progress, verbose, and information records from the execution of the script or cmdlet.

Data Type Records
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Records with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PSRemotingException Thrown when the Host within the PowerShell Session Details is invalid (e.g. host does not exist or invalid characters/whitespace).
Thrown when the Host within the PowerShell Session Details does not have PSRemoting configured correctly.
Thrown when the Host within the PowerShell Session Details is a host name; is being accessed through a private or domain network, and Kerberos authentication is disabled on the host’s WinRM service or the server’s WinRM client.
Thrown when the Host within the PowerShell Session Details is a host name; is being accessed through a public network, and its name is not on the server’s WinRM TrustedHosts list.
Thrown when the Host within the PowerShell Session Details is an IP Address; is being accessed through any network (i.e. public, private or domain), and is not on the server’s WinRM TrustedHosts list.
Thrown when the Host within the PowerShell Session Details is an IP Address being accessed through any network (i.e. public, private or domain) or a host name being accessed through a public network, and Negotiate authentication is disabled on the host’s WinRM service.
Thrown when the Port within the PowerShell Session Details is invalid.
Thrown when the UseSsl is false and the specified Port within the PowerShell Session Details is not configured for HTTP protocols.
Thrown when the UseSsl is true and the specified Port within the PowerShell Session Details is not configured for HTTPS protocols.
Thrown when the UseSsl is true and the host does not have a valid certificate configured.
Thrown when the Domain, Username, or Password in the Credentials within the PowerShell Session Details is invalid.
Thrown when the Domain in the Credentials within the PowerShell Session Details is null or empty and is required.
Thrown when the user does not have the correct user permissions to execute PowerShell scripts or cmdlets on the Host.
Thrown when the PsConfiguration within the PowerShell Session Details is invalid or is not configured on the Host.
PSException Thrown when the Script contains any unexpected or invalid tokens.
Thrown when the Script is missing any necessary tokens.
PropertyNullException Thrown when the Script is null.
Thrown when PowerShell Session Details is null.
Thrown when the ServerDetails within the PowerShell Session Details is null.
Thrown when the Host within the ServerDetails within the PowerShell Session Details is null.
Thrown when the Credentials within the PowerShell Session Details is null.
Thrown when the Username in the Credentials within the PowerShell Session Details is null.
Thrown when the Password in the Credentials within the PowerShell Session Details is null.
PropertyEmptyException Thrown when Script is empty.
Thrown when the Host within the ServerDetails within the PowerShell Session Details is empty.
Thrown when the Username in the Credentials within the PowerShell Session Details is empty.
Thrown when the Password in the Credentials within the PowerShell Session Details is empty.
PropertyEmptyException Thrown when the Port within the ServerDetails within the PowerShell Session Details is below 1 or above 65535.

Remarks

Opening Sessions

The Execute PowerShell Script block automatically handles creating and opening session for the specified PowerShell Session Details using the following rules:

  • If a session does not exist, a new session will be created, opened and used when the block runs.
  • If a session already exists but is closed, the session will be opened and used when the block runs.
  • If a session already exists and is open, the session will used the block runs.

For information on how to explicitly close a session, please see Closing Sessions.

Closing Sessions

Sessions can be explicitly closed by setting Close Session to true. This causes the session to be closed after the Script has been executed.

For information on how to open a session, please see Opening Sessions.

Known Limitations

None

6.3.18 - Schedules

Blocks related to working with Schedules.

6.3.18.1 - Wait For

Wait for certain events to occur (i.e. a duration to pass).

6.3.18.1.1 - Wait For Duration

Waits for a specified time period (Years, Months, Days, Hours, Minutes, Seconds and Milliseconds).
Icon

Wait For Duration

(Cortex.Blocks.Schedules.WaitFor.WaitForDurationBlock)

Description

Waits for a specified Duration.

Examples

Wait for duration

This example will wait for 30 seconds.

Properties

Property Value Notes
Duration ($)Duration, with value of {"Years": 0, "Months": 0, "Days": 0, "Hours": 0, "Minutes": 0, "Seconds": 30, "Milliseconds": 0} ($)Duration is a variable of type TimePeriod

Result

The block will wait for 30 seconds before completing, at which stage the flow execution will proceed to the next block.


Properties

Duration

The Duration to wait for.

Duration can have positive and negative components where components are:

  • Years
  • Months
  • Days
  • Hours
  • Minutes
  • Seconds
  • Milliseconds

When waiting for Duration, the block will calculate the date time to wait until by adding the Duration to the current date time. It will first add years, followed by months, days, hours, minutes, seconds and finally milliseconds.

When adding months, if the current day component is greater than the last day in the resultant month, it will update the day to the last day for that month (e.g. adding one month onto 2021-01-31T23:59:59+00:00 will equate to 2021-02-28T23:59:59+00:00).

Data Type TimePeriod
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Years: 0
Months: 0
Days: 0
Hours: 0
Minutes: 0
Seconds: 0
Milliseconds: 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentOutOfRangeException Thrown when any of the values or the sum of components of Duration are out of range.
PropertyValueOutOfRangeException Thrown when Duration is negative (i.e. the sum of the components of Duration is less than 0 milliseconds).

Remarks

No remarks for the block.

6.3.19 - Ssh

Blocks related to working with SSH.

6.3.19.1 - Execute Ssh Command

Blocks related to executing SSH commands.

6.3.19.1.1 - Execute Ssh Command

Executes an SSH command on the specified host.
Icon

Execute Ssh Command

("Cortex.Blocks.Ssh.ExecuteSshCommand.ExecuteSshCommandBlock)

Description

Connects to a host using the Ssh Session Details, and executes a Command, returning the Response and Ssh Logs.

Close Session can be specified to choose whether the session on the host is closed or is kept open for use on subsequent Execute Ssh Command blocks.

Examples

Execute a Command using UserCredentials

This example will execute a Command on the server with the following details:

  • Host - "localhost"
  • Port - 22
  • Domain - "domain"
  • Username - "username"
  • Password - "password"

Properties

Property Value Notes
Command ($)Command with value "ipconfig" ($)Command is a variable of type EncryptableText
Ssh Session Details ($)SshSessionDetails with value {"Host": "localhost", "Port": 22, "Credentials": {"Domain": "domain", "Username": "username", "Password": "encryptedPassword"}, "TerminalPrompt": "(.*(~(.*[\\r\\n]?)\\$|>))"}

In this example ($)SshSessionDetails has been set up using the following Expression:

new SshSessionDetails("localhost", 22, new UserCredentials("domain", "username", "encryptedPassword"), @"(.*(~(.*[\r\n]?)\$|>))")
($)SshSessionDetails is a variable of type SshSessionDetails
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean
Configuration Settings ($)ConfigurationSettings, with no value ($)CloseSession is a variable of type Dictionary<String, EncryptableText>
Response ($)Response, with no value ($)Response will be set to the type String
Ssh Logs ($)SshLogs, with no value ($)SshLogs will be set to the type SshLogs

Result

Running the Command results in the variable ($)Response being updated to the following:

Windows IP Configuration

Ethernet adapter Ethernet 3:

Connection-specific DNS Suffix. : reddog.microsoft.com
Link-local IPv6 Address. . . . . : fe80::78eb:a051:2b84:e8bd%6
IPv4 Address. . . . . . . . . . . : 10.3.0.4
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 10.3.0.1

It also results in the variable ($)SshLogs being updated to the following:

{
    "WelcomeMessage": "Last login: Tue Mar  1 06:50:23 2022 from 10.8.0.224",
    "Logs": "[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange.[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange..."
}

Note that more logs are included in this example, but have been omitted from ($)SshLogs.Logs.


Execute a Command using SshCertificateCredentials

This example will execute a Command on the server with the following details:

  • Host - "localhost"
  • Port - 22
  • Domain - "domain"

The server can be connected to using a valid certificate.

Properties

Property Value Notes
Command ($)Command with value "ipconfig" ($)Command is a variable of type EncryptableText
Ssh Session Details ($)SshSessionDetails with value {"Host": "localhost", "Port": 22, "Credentials": {"Domain": "domain", "Username": "username", "CertificatePath": "C:\\Certificate.pfx", "CertificatePassword": "encryptedCertificatePassword"}, "TerminalPrompt": "(.*(~(.*[\\r\\n]?)\\$|>))"}

In this example ($)SshSessionDetails has been set up using the following Expression:

new SshSessionDetails("localhost", 22, new SshCertificateCredentials("domain", "username", @"C\Certificate.pfx", "encryptedCertificatePassword"), @"(.*(~(.*[\r\n]?)\$|>))")
($)SshSessionDetails is a variable of type SshSessionDetails
Close Session ($)CloseSession with value true ($)CloseSession is a variable of type Boolean
Configuration Settings ($)ConfigurationSettings, with no value ($)CloseSession is a variable of type Dictionary<String, EncryptableText>
Response ($)Response, with no value ($)Response will be set to the type String
Ssh Logs ($)SshLogs, with no value ($)SshLogs will be set to the type SshLogs

Result

Running the Command results in the variable ($)Response being updated to the following:

Windows IP Configuration

Ethernet adapter Ethernet 3:

Connection-specific DNS Suffix. : reddog.microsoft.com
Link-local IPv6 Address. . . . . : fe80::78eb:a051:2b84:e8bd%6
IPv4 Address. . . . . . . . . . . : 10.3.0.4
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 10.3.0.1

It also results in the variable ($)SshLogs being updated to the following:

{
    "WelcomeMessage": "Last login: Tue Mar  1 06:50:23 2022 from 10.8.0.224",
    "Logs": "[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange.[Info] Sending local version: \"SSH-2.0-IPWorks SSH Client 2020\".\r\n[Info] Read remote version string: \"SSH-2.0-OpenSSH_4.7p1 Debian-8ubuntu1.2\".\r\n[Info] Beginning key exchange..."
}

Note that more logs are included in this example, but have been omitted from ($)SshLogs.Logs.


Properties

Command

The Command that will be executed on the Host specified in the Ssh Session Details.

Data Type EncryptableText
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Ssh Session Details

The Ssh Session Details object that includes all of the information required to open and maintain a SSH session. This property contains all of the information in relation to the server the Command will be executed on, these are:

Data Type SshSessionDetails
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)SshSessionDetails with no value

Close Session

Close Session can be specified to choose whether the session on the Host is closed or is kept open for use on subsequent Execute Ssh Command blocks, this defaults to false if left blank, please see Closing Sessions for more information.

Data Type Boolean
Property Type Input
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Configuration Settings

The Configuration Settings for the SSH connection and execution.

Data Type IDictionary<String, dynamic>
Property Type Input
Is Advanced true
Default Editor Expression
Default Value IDictionary<String, dynamic> with value shown below:
new Dictionary<string, dynamic> {
    { "TerminalWidth", 200 },
    { "TerminalType", "vt100" },
    { "Timeout", 60 },
    { "EndOfLineCharacters", "\r" },
    { "CancelCommand", "\x03" },
}

Response

The SSH Response that is returned from the execution of the Command on the Host specified in the Ssh Session Details.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Response with no value

Ssh Logs

The Ssh Logs that is returned from the execution of the Command on the host specified in the Ssh Session Details. This property contains all of the information in relation to the logs returned by the Command, these are:

  • WelcomeMessage
  • Logs
Data Type SshLogs
Property Type Output
Is Advanced true
Default Editor Variable
Default Value ($)SshLogs with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Command is null.
Thrown when the Ssh Session Details is null.
Thrown when the Host within the Ssh Session Details is null.
Thrown when the Credentials within the Ssh Session Details is null.
Thrown when using SshCertificateCredentials, the CertificatePath in the specified Credentials within the Ssh Session Details is null.
PropertyEmptyException Thrown when the specified Host within the Ssh Session Details is empty.
Thrown when the CertificatePath in the specified Credentials within the Ssh Session Details is empty.
PropertyValueOutOfRangeException Thrown when the specified Port within the Ssh Session Details is below 1 or above 65535.
SshClientException Thrown when one or more settings in Configuration Settings are invalid. (includes a dictionary of SettingName: ExceptionMessage from IPWorksSSHSshClientException)
Thrown when the specified Host within the Ssh Session Details is invalid.
Thrown when the specified Port within the Ssh Session Details is invalid.
Thrown when the server host key has not been accepted.
Thrown when using UserCredentials, the specified domain, username or password within Credentials is invalid.
Thrown when using SshCertificateCredentials, the specified Domain, Username, CertificatePath or CertificatePassword is invalid.
Thrown when the Host exits without using Close Session, returning the response received up to the point the host exited the session.
SshResponseException Thrown if the specified TerminalPrompt does not match the terminal prompt on the host causing the execution to timeout or the timeout was too short to allow for data to be received.
RegexMatchTimeoutException Thrown when the execution time of the regular expression pattern-matching exceeds the time-out interval.
RegexParsingFailedException Thrown when TerminalPrompt within Ssh Session Details contains invalid regex.

Remarks

Opening Sessions

The Execute Ssh Command block automatically handles creating and opening session for the specified Ssh Session Details using the following rules:

  • If a session does not exist, a new session will be created, opened and used when the block runs.
  • If a session already exists but is closed, the session will be opened and used when the block runs.
  • If a session already exists and is open, the session will used the block runs.

For information on how to explicitly close a session, please see Closing Sessions.

Closing Sessions

Sessions can be explicitly closed by setting Close Session to true. This causes the session to be closed after the Command has been executed.

For information on how to open a session, please see Opening Sessions.

Known Limitations

None

6.3.20 - Text

Blocks related to working with Text.

6.3.20.1 - Add Text

Add text to another text.

6.3.20.1.1 - Add Text After Index

Adds text to another text after a given index.
Icon

Add Text After Index

(Cortex.Blocks.Text.AddText.AddTextAfterIndexBlock)

Description

Adds Text To Add to another Text after the given Index.

Examples

Add Text To Add to another Text after the given Index

This example will add "|" after "A" (which is at index 0) in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

"A" is at index 0 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, adding "|" after index 0 results in the variable ($)Text being updated to the following:

"A|BCDEFGHIJKLMNOPQRSTUVWXYZ"

Add null or empty Text To Add to another Text after the given Index

This example will try to add null or "" after "A" (which is at index 0) in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value null or "" ($)TextToAdd is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding null or "" performs no operation as there is nothing to add, so the variable ($)Text will remain as follows:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text where the Text To Add is added.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Add

The Text To Add to the Text after the given Index.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Index

The Index to add the Text To Add after.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Index is less than zero or greater than the length of Text - 1.

Remarks

Null or empty Text To Add

If Text To Add is null or empty (i.e. "") nothing is added to Text. See Example above.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text To Add added in the correct place and re-assigns it to the variable specified in the Text property.

6.3.20.1.2 - Add Text At Beginning

Adds text at the beginning of another text.
Icon

Add Text At Beginning

(Cortex.Blocks.Text.AddText.AddTextAtBeginningBlock)

Description

Adds Text To Add at the beginning of another Text.

Examples

Add Text To Add at the beginning of another Text

This example will add "|" at the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String

Result

Adding "|" at the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)Text being updated to the following:

"|ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Add Text To Add at the beginning of a null or empty Text

This example will try to add "|" at the beginning of null or "".

Properties

Property Value Notes
Text ($)Text, with value null or "" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String

Result

Adding "|" to null or "" results in the variable ($)Text being updated to the following:

"|"

Add null or empty Text To Add at the beginning of another Text

This example will try to add null or "" at the beginnning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value null or "" ($)TextToAdd is a variable of type String

Result

Adding null or "" performs no operation as there is nothing to add, so the variable ($)Text will remain as follows:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text where the Text To Add is added.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Add

The Text To Add at the beginning of the Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Exceptions

No exceptions are thrown by the block.

Remarks

Null or empty Text

If Text is null or empty (i.e. "") it is replaced with the Text To Add. See Example above.

Null or empty Text To Add

If Text To Add is null or empty (i.e. "") nothing is added to Text. See Example above.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text To Add added in the correct place and re-assigns it to the variable specified in the Text property.

6.3.20.1.3 - Add Text At End

Adds text at the end of another text.
Icon

Add Text At End

(Cortex.Blocks.Text.AddText.AddTextAtEndBlock)

Description

Adds Text To Add at the end of another Text.

Examples

Add Text To Add at the end of another Text

This example will add "|" at the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String

Result

Adding "|" at the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)Text being updated to the following:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ|"

Add Text To Add at the end of a null or empty Text

This example will try to add "|" at the end of null or "".

Properties

Property Value Notes
Text ($)Text, with value null or "" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String

Result

Adding "|" to null or "" results in the variable ($)Text being updated to the following:

"|"

Add null or empty Text To Add at the end of another Text

This example will try to add null or "" at the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value null or "" ($)TextToAdd is a variable of type String

Result

Adding null or "" performs no operation as there is nothing to add, so the variable ($)Text will remain as follows:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text where the Text To Add is added.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Add

The Text To Add at the end of the Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Exceptions

No exceptions are thrown by the block.

Remarks

Null or empty Text

If Text is null or empty (i.e. "") it is replaced with the Text To Add. See Example above.

Null or empty Text To Add

If Text To Add is null or empty (i.e. "") nothing is added to Text. See Example above.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text To Add added in the correct place and re-assigns it to the variable specified in the Text property.

6.3.20.1.4 - Add Text Before Index

Adds text to another text before the specified index.
Icon

Add Text Before Index

(Cortex.Blocks.Text.AddText.AddTextBeforeIndexBlock)

Description

Adds Text To Add to another Text before the specified Index.

Examples

Add Text To Add to another Text before the given Index

This example will add "|" before "A" (which is at index 0) in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value "|" ($)TextToAdd is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

"A" is at index 0 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, adding "|" before index 0 results in the variable ($)Text being updated to the following:

"|ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Add null or empty Text To Add to another Text before the given Index

This example will try to add null or "" before "A" (which is at index 0) in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Text To Add ($)TextToAdd, with value null or "" ($)TextToAdd is a variable of type String
Index ($)Index, with value 0 ($)Index is a variable of type Int32

Result

Adding null or "" performs no operation as there is nothing to add, so the variable ($)Text will remain as follows:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text where the Text To Add is added.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Add

The Text To Add to the Text before the given Index.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Index

The Index to add the Text To Add before.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Index is less than zero or greater than the length of Text - 1.

Remarks

Null or empty Text To Add

If Text To Add is null or empty (i.e. "") nothing is added to Text. See Example above.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text To Add added in the correct place and re-assigns it to the variable specified in the Text property.

6.3.20.2 - Contains Text

Check if text is contained in another text.

6.3.20.2.1 - Contains All Text

Checks if text contains all of the texts in a given set of texts.
Icon

Contains All Text

(Cortex.Blocks.Text.ContainsText.ContainsAllTextBlock)

Description

Checks if Text contains all of the texts in a given set of Texts To Find.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check.

Examples

Text contains all of the texts in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains all of the texts in ["The", "quick", "brown", "fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["The", "quick", "brown", "fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains All Text ($)ContainsAllText, with no value ($)ContainsAllText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains all of the texts in ["The", "quick", "brown", "fox"]. Therefore, the variable ($)ContainsAllText will be updated to the following:

true

Text does not contain all of the texts in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains all of the texts in ["the", "slow", "brown", "fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["the", "slow", "brown", "fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains All Text ($)ContainsAllText, with no value ($)ContainsAllText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" does not contain all of the texts in ["the", "slow", "brown", "fox"]; "slow" is missing, and "the" does not match "The" as the specified Comparison Type uses case-sensitive matching. Therefore, the variable ($)ContainsAllText will be updated to the following:

false

Text contains text that matches all of the patterns in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches all of the patterns in ["?he", "?uick", "*?own", "fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["?he", "?uick", "*?own", "fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains All Text ($)ContainsAllText, with no value ($)ContainsAllText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains text that matches all of the patterns in ["?he", "?uick", "*?own", "fox"]. Therefore, the variable ($)ContainsAllText will be updated to the following:

true

Text contains text that matches all of the regexes in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches all of the regexes in ["^The", "(quick|fast)", "b.* ", "(fox|Fox)"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["^The", "(quick|fast)", "b.* ", "(fox|Fox)"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains All Text ($)ContainsAllText, with no value ($)ContainsAllText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains text that matches all of the regexes in ["^The", "(quick|fast)", "b.* ", "(fox|Fox)"]. Therefore, the variable ($)ContainsAllText will be updated to the following:

true

Properties

Text

The Text to check whether it contains all of the texts in the given set of Texts To Find.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Texts To Find

The set of Texts To Find to check are all contained in Text.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<string>() {}

Search Options

Search Options can be specified to choose whether items in Texts To Find should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Texts To Find it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to determine whether each text in Texts To Find is contained in Text

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Contains All Text

The result of the contains all text check.

If all of the texts in Texts To Find are contained in Text, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsAllText with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
PropertyNullException Thrown when Texts To Find is null.
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and one or more items in Texts To Find are not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. ""), the variable specified in the Contains All Text property is set to false.

Null or empty Texts To Find

If Texts To Find is empty or contains any null or empty (i.e. "") text, the variable specified in the Contains All Text property is set to false.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.2.2 - Contains Any Text

Checks if text contains any of the texts in a given set of texts.
Icon

Contains Any Text

(Cortex.Blocks.Text.ContainsText.ContainsAnyTextBlock)

Description

Checks if Text contains any of the texts in a given set of Texts To Find.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check.

Examples

Text contains any of the texts in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains at least one of the texts in ["The", "fast", "red", "fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["The", "fast", "red", "fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Any Text ($)ContainsAnyText, with no value ($)ContainsAnyText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains the text "The" and "fox" in ["The", "fast", "red", "fox"]. Therefore, the variable ($)ContainsAnyText will be updated to the following:

true

Text does not contain any of the texts in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains at least one of the texts in ["the", "slow", "red", "Fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["the", "slow", "red", "Fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Any Text ($)ContainsAnyText, with no value ($)ContainsAnyText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" does not contain any of the texts in ["the", "slow", "red", "Flow"]; "slow" and "red" are both missing, and "the" and "Fox" do not match "The" and "fox" respectively as the specified Comparison Type uses case-sensitive matching. Therefore, the variable ($)ContainsAnyText will be updated to the following:

false

Text contains text that matches any of the patterns in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches any of the patterns in ["?he", "Q?ick", "B*?wn", "Fox"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["?he", "Q?ick", "B*?wn", "Fox"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Any Text ($)ContainsAnyText, with no value ($)ContainsAnyText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains text that matches one of the patterns in ["?he", "Q?ick", "B*?wn", "Fox"]; "?he" matches "The" and "the". Therefore, the variable ($)ContainsAnyText will be updated to the following:

true

Text contains text that matches any of the regexes in Texts To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches any of the regexes in ["^The", "(Quick|Fast)", "b.* ", "(fox|Fox)$"].

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Texts To Find ($)TextsToFind, with value ["^The", "(Quick|Fast)", "b.* ", "(fox|Fox)$"] ($)TextsToFind is a variable of type IEnumerable<String>
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Any Text ($)ContainsAnyText, with no value ($)ContainsAnyText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains text that matches any of the regexes in ["^The", "(Quick|Fast)", "b.* ", "(fox|Fox)$"]; "^The" matches "The" at the start of the sentence. Therefore, the variable ($)ContainsAnyText will be updated to the following:

true

Properties

Text

The Text to check whether it contains any of the texts in the given set of Texts To Find.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Texts To Find

The set of Texts To Find to check any are contained in Text.

Data Type IEnumerable<String>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<string>() {}

Search Options

Search Options can be specified to choose whether items in Texts To Find should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Texts To Find it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to determine whether each text in Texts To Find is contained in Text

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Contains Any Text

The result of the contains any text check.

If any of the texts in Texts To Find is contained in Text, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsAnyText with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
PropertyNullException Thrown when Texts To Find is null.
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and one or more items in Texts To Find are not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. ""), the variable specified in the Contains Any Text property is set to false.

Null or empty Texts To Find

If Texts To Find is empty or only contains null or empty (i.e. "") text, the variable specified in the Contains Any Text property is set to false.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.2.3 - Contains Text

Checks if text contains another text.
Icon

Contains Text

(Cortex.Blocks.Text.ContainsText.ContainsTextBlock)

Description

Checks if Text contains Text To Find.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to perform the check.

Examples

Text contains Text To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains the text "quick brown fox".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "quick brown fox" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Text ($)ContainsText, with no value ($)ContainsText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains the text "quick brown fox". Therefore, the variable ($)ContainsText will be updated to the following:

true

Text does not contain Text To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains the text "quick red fox".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "quick red fox" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Text ($)ContainsText, with no value ($)ContainsText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" does not contain "quick red fox". Therefore, the variable ($)ContainsText will be updated to the following:

false

Text contains text that matches the pattern in Text To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches the pattern "*?he".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "?he" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Text ($)ContainsText, with no value ($)ContainsText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains "The" and "the" that matches the pattern "?he". Therefore, the variable ($)ContainsText will be updated to the following:

true

Text contains text that matches the regex in Text To Find

This example will check whether "The quick brown fox jumps over the lazy dog" contains text that matches the regex "^The".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "^The" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Contains Text ($)ContainsText, with no value ($)ContainsText is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" contains "The" at the start of the sentence that matches the regex "^The". Therefore, the variable ($)ContainsText will be updated to the following:

true

Properties

Text

The Text to check whether it contains Text To Find.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Find

The Text To Find in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Search Options

Search Options can be specified to choose whether Text To Find should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Find it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to determine whether Text To Find is contained in Text

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Contains Text

The result of the contains text check.

If Text To Find is contained in Text, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)ContainsText with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Find is not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. ""), the variable specified in the Contains Text property is set to false.

Null or empty Text To Find

If Text To Find is null or empty (i.e. ""), the variable specified in the Contains Text property is set to false.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.3 - Convert To

Convert text to a different format (e.g. "lowercase", "UPPERCASE", "Title Case", "camelCase", "PascalCase").

6.3.20.3.1 - Convert To Camel Case

Converts text to camel case (e.g. "camelCase").
Icon

Convert To Camel Case

(Cortex.Blocks.Text.ConvertTo.ConvertToCamelCaseBlock)

Description

Converts Text to camel case.

Converting to camel case will result in all words (except the first) having their first letter capitalized, all other letters lower cased, and all spaces and punctuation being removed (e.g. "TEXT to convert to camel-case!" will be converted to "textToConvertToCamelCase").

Examples

Text converted to camel case

This example will convert "The quick brown fox jumps over the lazy dog" to camel case.

It performs a culture-insensitive conversion of the text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Culture Info ($)CultureInfo, with value CultureInfo.InvariantCulture ($)CultureInfo is a variable of type CultureInfo

Result

Converting "The quick brown fox jumps over the lazy dog" to camel case will result in the variable ($)Text being updated to the following:

"theQuickBrownFoxJumpsOverTheLazyDog"

Properties

Text

The Text to convert to camel case.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Culture Info

The Culture Info used to perform the conversion of the Text.

For information about the supported values for the Culture Info property and examples of how it affects casing rules, please see Casing.

Data Type CultureInfo
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when the culture identifier of the Culture Info is invalid (e.g. new CultureInfo("InvalidCultureIdentifier")). See Value Is Invalid.

Remarks

Culture Info

For information about the supported values for the CultureInfo property and examples of how it affects casing rules, please see Casing.

Null Culture Info

If Culture Info is null, it will be set to CultureInfo.InvariantCulture.

Null or empty Text

If Text is null or empty (i.e. ""), no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text converted to camel case and re-assigns it to the variable specified in the Text property.

6.3.20.3.2 - Convert To Lower Case

Converts text to lower case (e.g. "lowercase").
Icon

Convert To Lower Case

(Cortex.Blocks.Text.ConvertTo.ConvertToLowerCaseBlock)

Description

Converts Text to lower case.

Converting to lower case will result in all letters being lower cased; spaces and punctuation will be preserved (e.g. "TEXT to convert to lower-case!" will be converted to "text to convert to lower-case!").

Examples

Text converted to lower case

This example will convert "The quick brown fox jumps over the lazy dog" to lower case.

It performs a culture-insensitive conversion of the text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Culture Info ($)CultureInfo, with value CultureInfo.InvariantCulture ($)CultureInfo is a variable of type CultureInfo

Result

Converting "The quick brown fox jumps over the lazy dog" to lower case will result in the variable ($)Text being updated to the following:

"the quick brown fox jumps over the lazy dog"

Properties

Text

The Text to convert to lower case.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Culture Info

The Culture Info used to perform the conversion of the Text.

For information about the supported values for the Culture Info property and examples of how it affects casing rules, please see Casing.

Data Type CultureInfo
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when the culture identifier of the Culture Info is invalid (e.g. new CultureInfo("InvalidCultureIdentifier")). See Value Is Invalid.

Remarks

Culture Info

For information about the supported values for the CultureInfo property and examples of how it affects casing rules, please see Casing.

Null Culture Info

If Culture Info is null, it will be set to CultureInfo.InvariantCulture.

Null or empty Text

If Text is null or empty (i.e. ""), no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text converted to lower case and re-assigns it to the variable specified in the Text property.

6.3.20.3.3 - Convert To Pascal Case

Converts text to pascal case (e.g. "PascalCase").
Icon

Convert To Pascal Case

(Cortex.Blocks.Text.ConvertTo.ConvertToPascalCaseBlock)

Description

Converts Text to pascal case.

Converting to pascal case will result in all words having their first letter capitalized, all other letters lower cased, and all spaces and punctuation being removed (e.g. "TEXT to convert to pascal-case!" will be converted to "TextToConvertToPascalCase").

Examples

Text converted to pascal case

This example will convert "The quick brown fox jumps over the lazy dog" to pascal case.

It performs a culture-insensitive conversion of the text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Culture Info ($)CultureInfo, with value CultureInfo.InvariantCulture ($)CultureInfo is a variable of type CultureInfo

Result

Converting "The quick brown fox jumps over the lazy dog" to pascal case will result in the variable ($)Text being updated to the following:

"TheQuickBrownFoxJumpsOverTheLazyDog"

Properties

Text

The Text to convert to pascal case.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Culture Info

The Culture Info used to perform the conversion of the Text.

For information about the supported values for the Culture Info property and examples of how it affects casing rules, please see Casing.

Data Type CultureInfo
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when the culture identifier of the Culture Info is invalid (e.g. new CultureInfo("InvalidCultureIdentifier")). See Value Is Invalid.

Remarks

Culture Info

For information about the supported values for the CultureInfo property and examples of how it affects casing rules, please see Casing.

Null Culture Info

If Culture Info is null, it will be set to CultureInfo.InvariantCulture.

Null or empty Text

If Text is null or empty (i.e. ""), no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text converted to pascal case and re-assigns it to the variable specified in the Text property.

6.3.20.3.4 - Convert To Title Case

Converts text to title case (e.g. "Title Case").
Icon

Convert To Title Case

(Cortex.Blocks.Text.ConvertTo.ConvertToTitleCaseBlock)

Description

Converts Text to title case.

Converting to title case will result in all words having their first letter capitalized and all other letters lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased; spaces and punctuation will be preserved (e.g. "TEXT to convert to title-case!" will be converted to "TEXT To Convert To Title-Case!").

Examples

Text converted to title case

This example will convert "The quick brown fox jumps over the lazy dog" to title case.

It performs a culture-insensitive conversion of the text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Culture Info ($)CultureInfo, with value CultureInfo.InvariantCulture ($)CultureInfo is a variable of type CultureInfo

Result

Converting "The quick brown fox jumps over the lazy dog" to title case will result in the variable ($)Text being updated to the following:

"The Quick Brown Fox Jumps Over The Lazy Dog"

Properties

Text

The Text to convert to title case.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Culture Info

The Culture Info used to perform the conversion of the Text.

For information about the supported values for the Culture Info property and examples of how it affects casing rules, please see Casing.

Data Type CultureInfo
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when the culture identifier of the Culture Info is invalid (e.g. new CultureInfo("InvalidCultureIdentifier")). See Value Is Invalid.

Remarks

Culture Info

For information about the supported values for the CultureInfo property and examples of how it affects casing rules, please see Casing.

Null Culture Info

If Culture Info is null, it will be set to CultureInfo.InvariantCulture.

Null or empty Text

If Text is null or empty (i.e. ""), no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text converted to title case and re-assigns it to the variable specified in the Text property.

6.3.20.3.5 - Convert To Upper Case

Converts text to upper case (e.g. "UPPERCASE").
Icon

Convert To Upper Case

(Cortex.Blocks.Text.ConvertTo.ConvertToUpperCaseBlock)

Description

Converts Text to upper case.

Converting to upper case will result in all letters being upper cased; spaces and punctuation will be preserved (e.g. "TEXT to convert to upper-case!" will be converted to "TEXT TO CONVERT TO UPPER-CASE!").

Examples

Text converted to upper case

This example will convert "The quick brown fox jumps over the lazy dog" to upper case.

It performs a culture-insensitive conversion of the text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Culture Info ($)CultureInfo, with value CultureInfo.InvariantCulture ($)CultureInfo is a variable of type CultureInfo

Result

Converting "The quick brown fox jumps over the lazy dog" to upper case will result in the variable ($)Text being updated to the following:

"THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG"

Properties

Text

The Text to convert to upper case.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Culture Info

The Culture Info used to perform the conversion of the Text.

For information about the supported values for the Culture Info property and examples of how it affects casing rules, please see Casing.

Data Type CultureInfo
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Exceptions

The exceptions thrown by the block can be found below:

Name Description
InvalidPropertyValueException Thrown when the culture identifier of the Culture Info is invalid (e.g. new CultureInfo("InvalidCultureIdentifier")). See Value Is Invalid.

Remarks

Culture Info

For information about the supported values for the CultureInfo property and examples of how it affects casing rules, please see Casing.

Null Culture Info

If Culture Info is null, it will be set to CultureInfo.InvariantCulture.

Null or empty Text

If Text is null or empty (i.e. ""), no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Text converted to upper case and re-assigns it to the variable specified in the Text property.

6.3.20.4 - Find And Remove Text

Find text in another text, and remove it.

6.3.20.4.1 - Find And Remove All Text

Finds and removes all occurrences of text from a given text.
Icon

Find And Remove All Text

(Cortex.Blocks.Text.FindAndRemoveText.FindAndRemoveAllTextBlock)

Description

Finds and removes all occurrences of Text To Remove from a given Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Remove.

Examples

Remove all occurrences of Text To Remove (Ordinal)

This example will find and remove all occurrences of "The" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "The" ($)TextToRemove is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over the lazy dog"

Remove all occurrences of Text To Remove (Ordinal Ignore Case)

This example will find and remove all occurrences of "The" from "The quick brown fox jumps over the lazy dog".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "The" ($)TextToRemove is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison

Result

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over  lazy dog"

Remove all occurrences that match the pattern in Text To Remove

This example will find and remove all occurrences of text that match the pattern "?he" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "?he" ($)TextToRemove is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

"The quick brown fox jumps over the lazy dog" contains "The" and "the" that matches the pattern "?he". Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over  lazy dog"

Remove all occurrences that match the regex in Text To Remove

This example will find and remove all occurrences of text that match the regex "^The" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "^The" ($)TextToRemove is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

"The quick brown fox jumps over the lazy dog" contains "The" at the start of the sentence that matches the regex "^The". Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over the lazy dog"

Properties

Text

The Text to find and remove all occurrences of Text To Remove from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Remove

The Text To Remove all occurrences of, from Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Search Options

Search Options can be specified to choose whether Text To Remove should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Remove it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match occurrences of Text To Remove in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Remove is not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. "") there is nothing to remove from, so no operation is performed.

Null or empty Text To Remove

If Text To Remove is null or empty (i.e. "") there is nothing to remove, so no operation is performed.

Text To Remove is not present

If Text To Remove is not present there is nothing to remove, so no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String with all occurrences of Text To Remove removed and re-assigns it to the variable specified in the Text property.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.4.2 - Find And Remove Text

Finds and removes the specified occurrence of text from a given text.
Icon

Find And Remove Text

(Cortex.Blocks.Text.FindAndRemoveText.FindAndRemoveTextBlock)

Description

Finds and removes the specified Occurrence of Text To Remove from a given Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Remove.

Examples

Remove the first Occurrence of Text To Remove (Ordinal)

This example will find and remove the first occurrence of "The" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "The" ($)TextToRemove is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of 1 means find and remove the first occurrence; 2 means second etc.

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over the lazy dog"

Remove the last Occurrence of Text To Remove (Ordinal Ignore Case)

This example will find and remove the last occurrence of "The" from "The quick brown fox jumps over the lazy dog".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "The" ($)TextToRemove is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of -1, means find and remove the last occurrence; -2 means second last etc.

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second and last occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

"The quick brown fox jumps over  lazy dog"

Remove the first Occurrence matching the pattern in Text To Remove

This example will find and remove the first occurrence of text matching the pattern "?he" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "?he" ($)TextToRemove is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of 1 means find and remove the first occurrence; 2 means second etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the pattern "?he"; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

" quick brown fox jumps over the lazy dog"

Remove the last Occurrence matching the regex in Text To Remove

This example will find and remove the last occurrence of text matching the regex "(fox|dog)" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Remove ($)TextToRemove, with value "(fox|dog)" ($)TextToRemove is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of -1, means find and remove the last occurrence; -2 means second last etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the regex "(fox|dog)"; the first occurrence is "fox" and the second and last occurrence is "dog". Therefore, the variable ($)Text will be updated to the following:

"The quick brown fox jumps over the lazy "

Properties

Text

The Text to find and remove the specified Occurrence of Text To Remove from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Remove

The Text To Remove the specified Occurrence of, from Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Occurrence

The Occurrence of Text To Remove from Text.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Search Options

Search Options can be specified to choose whether Text To Remove should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Remove it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match occurrences of Text To Remove in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Remove is not a valid regex (e.g. ().

Remarks

Occurrences

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. "") there is nothing to remove from, so no operation is performed.

Null or empty Text To Remove

If Text To Remove is null or empty (i.e. "") there is nothing to remove, so no operation is performed.

Text To Remove or Occurrence is not present

If Text To Remove or the specified Occurrence is not present, there is nothing to remove, so no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String with the specified Occurrence of Text To Remove removed and re-assigns it to the variable specified in the Text property.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.5 - Find And Replace Text

Find text in another text, and replace it.

6.3.20.5.1 - Find And Replace All Text

Finds and replaces all occurrences of text in a given text.
Icon

Find And Replace All Text

(Cortex.Blocks.Text.FindAndReplaceText.FindAndReplaceAllTextBlock)

Description

Finds and replaces all occurrences of Text To Replace with the specified Replacement Text in a given Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Replace.

Examples

Replace all occurrences of Text To Replace (Ordinal)

This example will find and replace all occurrences of "The" in "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "The" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over the lazy dog"

Replace all occurrences of Text To Replace (Ordinal Ignore Case)

This example will find and replace all occurrences of "The" in "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "The" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison

Result

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over a lazy dog"

Replace all occurrences that match the pattern in Text To Replace

This example will find and replace all occurrences of text that match the pattern "?he" from "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "?he" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

"The quick brown fox jumps over the lazy dog" contains "The" and "the" that matches the pattern "?he". Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over a lazy dog"

Replace all occurrences that match the regex in Text To Replace

This example will find and replace all occurrences of text that match the regex "^The" from "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "^The" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

"The quick brown fox jumps over the lazy dog" contains "The" at the start of the sentence that matches the regex "^The". Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over the lazy dog"

Properties

Text

The Text to find and replace all occurrences of Text To Replace in.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Replace

The Text To Replace all occurrences with Replacement Text in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Replacement Text

The Replacement Text used to replace all occurrences of Text To Replace in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Search Options

Search Options can be specified to choose whether Text To Replace should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Replace it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match occurrences of Text To Replace in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Replace is not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. "") there is nothing to replace in, so no operation is performed.

Null or empty Text To Replace

If Text To Replace is null or empty (i.e. "") there is nothing to replace, so no operation is performed.

Null or empty Replacement Text

If Replacement Text is null or empty (i.e. "") all occurrences of Text To Replace are replaced with an empty text (i.e. "").

Text To Replace is not present

If Text To Replace is not present there is nothing to replace, so no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String with all occurrences of Text To Replace replaced and re-assigns it to the variable specified in the Text property.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.5.2 - Find And Replace Text

Finds and replaces the specified occurrence of text in a given text.
Icon

Find And Replace Text

(Cortex.Blocks.Text.FindAndReplaceText.FindAndReplaceTextBlock)

Description

Finds and replaces the specified Occurrence of Text To Replace with the specified Replacement Text in a given Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Replace.

Examples

Replace the first Occurrence of Text To Replace (Ordinal)

This example will find and replace the first occurrence of "The" in "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "The" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of 1 means find and replace the first occurrence; 2 means second etc.

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over the lazy dog"

Replace the last occurrence of Text To Replace (Ordinal Ignore Case)

This example will find and replace the last occurrence of "The" in "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "The" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of -1, means find and replace the last occurrence; -2 means second last etc.

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second and last occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

"The quick brown fox jumps over a lazy dog"

Replace the first Occurrence matching the pattern in Text To Replace

This example will find and replace the first occurrence of text matching the pattern "?he" from "The quick brown fox jumps over the lazy dog" with "a".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "?he" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "a" ($)ReplacementText is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of 1 means find and replace the first occurrence; 2 means second etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the pattern "?he"; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Text will be updated to the following:

"a quick brown fox jumps over the lazy dog"

Replace the last Occurrence matching the regex in Text To Replace

This example will find and replace the last occurrence of text matching the regex "(fox|dog)" from "The quick brown fox jumps over the lazy dog" with "cat".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Replace ($)TextToReplace, with value "(fox|dog)" ($)TextToReplace is a variable of type String
Replacement Text ($)ReplacementText, with value "cat" ($)ReplacementText is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison

Result

An Occurrence of -1, means find and replace the last occurrence; -2 means second last etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the regex "(fox|dog)"; the first occurrence is "fox" and the second and last occurrence is "dog". Therefore, the variable ($)Text will be updated to the following:

"The quick brown fox jumps over the lazy cat"

Properties

Text

The Text to find and replace the specified Occurrence of Text To Replace in.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Replace

The Text To Replace the specified Occurrence with Replacement Text in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Replacement Text

The Replacement Text used to replace the specified Occurrence of Text To Replace in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Occurrence

The Occurrence of Text To Replace in Text.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Search Options

Search Options can be specified to choose whether Text To Replace should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Replace it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match occurrences of Text To Replace in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Replace is not a valid regex (e.g. ().

Remarks

Occurrences

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. "") there is nothing to replace in, so no operation is performed.

Null or empty Text To Replace

If Text To Replace is null or empty (i.e. "") there is nothing to replace, so no operation is performed.

Null or empty Replacement Text

If Replacement Text is null or empty (i.e. "") the specified Occurrence of Text To Replace is replaced with an empty text (i.e. "").

Text To Replace or Occurrence is not present

If Text To Replace or the specified Occurrence is not present there is nothing to replace, so no operation is performed.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String with the specified Occurrence of Text To Replace replaced and re-assigns it to the variable specified in the Text property.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.6 - Format Text

Format text containing format parameters (i.e. {0}) by replacing them with other values.

6.3.20.6.1 - Format Text With Value

Formats text by replacing all {0} format parameters in a specified format template with a given value.
Icon

Format Text With Value

(Cortex.Blocks.Text.FormatText.FormatTextWithValueBlock`1)

Description

Replaces all {0} format parameters in the specified Format Template with the given Value, saving the result as Text.

An additional Format Provider option can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting).

Examples

Text Value

This example will format "Hello {0}" with "world!".

Properties

Property Value Notes
Format Template ($)FormatTemplate, with value "Hello {0}" ($)FormatTemplate is a variable of type String
Value ($)Value, with value "world!" ($)Value is a variable of type String
Format Provider ($)FormatProvider, with value null ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Formatting "Hello {0}" with "world!" results in the variable ($)Text being updated to the following:

"Hello world!"

Double Value using American English (“en-US”)

This example will format "Your final bill is {0:C2}" with 99.99.

The format parameter {0:C2} will display the double value as U.S currency to two decimal places (i.e. $99.99):

  • 0 - is replaced by the double value.
  • C - indicates to include the currency symbol for the specified culture (i.e. $).
  • 2 - indicates the number of decimal places to format the double value to.

For information about format templates and parameters, please see Text Formatting.

Properties

Property Value Notes
Format Template ($)FormatTemplate, with value "Your final bill is {0:C2}" ($)FormatTemplate is a variable of type String
Value ($)Value, with value 99.99 ($)Value is a variable of type Double
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Formatting "Your final bill is {0:C2}" with 99.99 results in the variable ($)Text being updated to the following:

"Your final bill is $99.99"

Properties

Format Template

Format Template can be specified to define the format of the resultant Text.

All {0} format parameters in Format Template will be replaced with Value.

If Format Template is not specified, null or empty (i.e. ""), or does not contain any {0} format parameters, nothing is replaced; Text will be set to the value of Format Template.

For information about format templates and parameters, please see Text Formatting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value @"{0}"

Value

The Value to replace all {0} format parameters with.

Value does not have to be text, it can be any data type. Any non-text value will be converted to its text representation when it is replaced.

For information about how types are converted to their text representation please see Converting Objects To Text.

Data Type TValue
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Format Provider

Format Provider can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting.).

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Data Type IFormatProvider
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Text

The formatted Text that results from replacing all {0} format parameters in Format Template with Value.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
FormatException Thrown when Format Template contains a format parameter not equal to zero (e.g. "Hello {1}").
Thrown when Format Template contains a format parameter that is invalid or not well-formed (e.g. "Cost is {0:Q2}, as "Q" is not a valid format parameter).

Remarks

Text Formatting

Please note that changes to operating system settings, could result in some of the examples above displaying different results.

For information about format templates and parameters, please see Text Formatting.

Null or Empty Format Template

If Format Template is not specified, null or empty (i.e. ""), or does not contain any {0} format parameters, nothing is replaced; Text will be set to the value of Format Template.

Null Format Provider

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

6.3.20.6.2 - Format Text With Values

Formats text by replacing all format parameters (e.g. {0} or {1} or {2}) in a specified format template with given values.
Icon

Format Text With Values

(Cortex.Blocks.Text.FormatText.FormatTextWithValuesBlock`1)

Description

Replaces all format parameters (e.g. {0} or {1} or {2}) in the given Format Template with the specified Values, saving the result as Text.

An additional Format Provider option can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting).

Examples

Text Values

This example will format "Hello {0} {1}" with ["Mr", "Smith"].

Properties

Property Value Notes
Format Template ($)FormatTemplate, with value "Hello {0} {1}" ($)FormatTemplate is a variable of type String
Values ($)Values, with value ["Mr", "Smith"] ($)Values is a variable of type IEnumerable<String>
Format Provider ($)FormatProvider, with value null ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

Formatting "Hello {0} {1}" with ["Mr", "Smith"] results in the variable ($)Text being updated to the following:

"Hello Mr Smith"

Multiple non-text values using American English (“en-US”)

This example will format "Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding." with [99.99, 0.8, 40].

The format parameter {0:C2} will display the 99.99 as U.S currency to two decimal places (i.e. $99.99):

  • 0 - is replaced by the double value 99.99.
  • C - indicates to include the currency symbol for the specified culture (i.e. $).
  • 2 - indicates to format the double value to two decimal places.

The format parameter {1:P0} will display the 0.8 as a percentage to zero decimal places (i.e. 80 %):

  • 1 - is replaced by the double value 0.8.
  • P - indicates the value should be formatted as a percentage.
  • 0 - indicates to format the percentage value to zero decimal places.

The format parameter {2:C2} will display the 40 as U.S currency to two decimal places (i.e. $40.00):

  • 2 - is replaced by the double value 40.
  • C - indicates to include the currency symbol for the specified culture (i.e. $).
  • 2 - indicates to format the double value to two decimal places.

For information about format templates and parameters, please see Text Formatting.

Properties

Property Value Notes
Format Template ($)FormatTemplate, with value "Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding." ($)FormatTemplate is a variable of type String
Values ($)Values, with value [99.99, 0.8, 40] ($)Values is a variable of type IEnumerable<Double>
Format Provider ($)FormatProvider, with value new CultureInfo("en-US") ($)FormatProvider is a variable of type IFormatProvider
Text ($)Text, with no value ($)Text is a variable that will be set to a String value

Result

"Your latest payment of {0:C2} has been received. You have paid {1:P0} of your total and have {2:C2} outstanding." with [99.99, 0.8, 40] results in the variable ($)Text being updated to the following:

"Your latest payment of $99.99 has been received. You have paid 80 % of your total and have $40.00 outstanding."

Properties

Format Template

Format Template can be specified to define the format of the resultant Text.

All format parameters (e.g. {0} or {1} or {2}) in Format Template will be replaced with the corresponding value in Values. Format parameter {0} will be replaced with the first value in Values; {1} will be replaced with the second value in Values etc.

The number of unique format parameters must be equal to or less than the number of items in Values.

The index of each format parameter must be equal to or less than the number of items in Values - 1.

If Format Template is not specified, null or empty (i.e. ""), or does not contain any format parameters, nothing is replaced; Text will be set to the value of Format Template.

For information about format templates and parameters, please see Text Formatting.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value @"{0} {1}"

Values

The Values to replace all format parameters with.

If a value does not have a corresponding format parameter, it is ignored.

Values does not have to contain all text values, it can contain any data types. Any non-text values will be converted to their text representation when they are replaced.

If any value is null or empty (i.e. ""), an empty text (i.e. "") will replace the corresponding format parameter.

For information about how types are converted to their text representation please see Converting Objects To Text.

Data Type IEnumerable<TValue>
Property Type Input
Is Advanced false
Default Editor Expression
Default Value new List<dynamic>() {0, "1"}

Format Provider

Format Provider can be specified to define the cultural rules used to control the formatting (e.g. new CultureInfo("en-US") will apply American English rules to the formatting.).

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

Data Type IFormatProvider
Property Type Input
Is Advanced true
Default Editor Expression
Default Value CultureInfo.InvariantCulture

Text

The formatted Text that results from replacing all format parameters in Format Template with corresponding Values.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
FormatException Thrown when Format Template contains a format parameter less than zero (e.g. "Hello {-1}") or greater than the count of Values - 1.
Thrown when Format Template contains a format parameter that is invalid or not well-formed (e.g. "Cost is {0:Q2}, as "Q" is not a valid format parameter).
PropertyNullException Thrown when Values is null.

Remarks

Text Formatting

Please note that changes to operating system settings, could result in some of the examples above displaying different results.

For information about format templates and parameters, please see Text Formatting.

Null or Empty Format Template

If Format Template is not specified, null or empty (i.e. ""), or does not contain any format parameters, nothing is replaced; Text will be set to the value of Format Template.

Null Format Provider

If Format Provider is not specified or null, CultureInfo.InvariantCulture will be used; CultureInfo.InvariantCulture is associated with the English language but not with any country/region. For more information, please see Invariant Culture rules.

6.3.20.7 - Get Index(es) of Text

Get the index for the specified occurrence of text, or the indexes of all occurrences of text contained in another text.

6.3.20.7.1 - Get Index Of Text

Gets the index of the specified occurrence of a text in another text.
Icon

Get Index Of Text

(Cortex.Blocks.Text.GetIndex.GetIndexOfTextBlock)

Description

Gets the Index of the specified Occurrence of Text To Find in Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Find.

Examples

Get the Index of the first Occurrence of Text To Find (Ordinal)

This example will get the index of the first occurrence of "The" in "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "The" ($)TextToFind is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of 1 means get the index of the first occurrence; 2 means second etc.

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Index will be updated to the following:

0

where 0 indicates the index of the first character of the first and only occurrence matching "The".


Get the Index of the last Occurrence of Text To Find (Ordinal Ignore Case)

This example will get the index of the last occurrence of "The" in "The quick brown fox jumps over the lazy dog".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "The" ($)TextToFind is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of -1 means get the index of the last occurrence; 2 means second last etc.

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second and last occurrence is "the". Therefore, the variable ($)Index will be updated to the following:

31

where 31 indicates the index of the first character of the last matching occurrence, "the".


Text does not contain Text To Find

This example will attempt to get the index of the first occurrence of "slow" in "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "slow" ($)TextToFind is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

"The quick brown fox jumps over the lazy dog" does not contain the text "slow", so the index cannot be found. Therefore, the variable ($)Index will be updated to the following:

-1

where -1 indicates that there are no matching occurrences.


Get the Index of the first Occurrence matching the pattern in Text To Find

This example will get the index of the first occurrence of text matching the pattern "?he" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "?he" ($)TextToFind is a variable of type String
Occurrence ($)Occurrence, with value 1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of 1 means get the index of the first occurrence; 2 means second etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the pattern "?he"; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Index will be updated to the following:

0

where 0 indicates the index of the first character of the first occurrence matching the pattern "?he".


Get the Index of the last Occurrence matching the regex in Text To Remove

This example will get the index of the last occurrence of text matching the regex "(fox|dog)" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "(fox|dog)" ($)TextToFind is a variable of type String
Occurrence ($)Occurrence, with value -1 ($)Occurrence is a variable of type Int32
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Index ($)Index, with no value ($)Index is a variable that will be set to an Int32 value

Result

An Occurrence of -1 means get the index of the last occurrence; 2 means second last etc.

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the regex "(fox|dog)"; the first occurrence is "fox" and the second and last occurrence is "dog". Therefore, the variable ($)Index will be updated to the following:

40

where 0 indicates the index of the first character of the last occurrence matching the regex "(fox|dog)".


Properties

Text

The Text to get the Index of the specified Occurrence of Text To Find from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Find

The Text To Find the Index of the specified Occurrence of, in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Occurrence

The specified Occurrence of Text To Find in Text.

For information about supported values for the Occurrence property and examples of how it can be used, please see Occurrences.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 1

Search Options

Search Options can be specified to choose whether Text To Find should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Find it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match Text To Find in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Index

Int32 indicating the Index of the first character of the specified Occurrence of Text To Find in Text.

If there is no specified Occurrence of Text To Find in Text, the specified variable will be set to -1.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Index with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Find is not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. ""), the variable specified in the Index property is set to -1.

Null or empty Text To Find

If Text To Find is null or empty (i.e. ""), the variable specified in the Index property is set to -1.

Occurrence is zero

If the Occurrence is set to 0, the variable specified in the Index property is set to -1.

Occurrence of Text To Find not found

If the specified Occurrence of Text To Find is not found in Text, the variable specified in the Index property is set to -1.

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.7.2 - Get Indexes Of Text

Gets the indexes of all occurrences of a text in another text.
Icon

Get Indexes Of Text

(Cortex.Blocks.Text.GetIndex.GetIndexesOfTextBlock)

Description

Gets the Indexes of all occurrences of Text To Find in Text.

Search Options can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to find the Text To Find.

Examples

Get Indexes of all occurrences of Text To Find (Ordinal)

This example will get the indexes of all occurrences of "The" in "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "The" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" only contains the text "The" once; "the" has a different case so does not match. Therefore, the variable ($)Indexes will be updated to the following:

[0]

where 0 indicates the index of the first character of the matching "The" occurrence.


Get Indexes of all occurrences of Text To Find (Ordinal Ignore Case)

This example will get the indexes of all occurrences of "The" in "The quick brown fox jumps over the lazy dog".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "The" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" contains the text "The" twice; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Indexes will be updated to the following:

[0, 31]

where 0 indicates the index of the first character of the matching "The" occurrence, and 31 indicates the index of the first character of the matching "the" occurrence.


Text does not contain Text To Find

This example will attempt to get the indexes of all occurrences of "slow" in "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "slow" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.ContainsText ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

"The quick brown fox jumps over the lazy dog" does not contain the text "slow", so the index cannot be found. Therefore, the variable ($)Indexes will be updated to the following:

[-1]

where -1 indicates that there are no matching occurrences.


Get Indexes of all occurrences matching the pattern in Text To Find

This example will get the indexes of all occurrences of text matching the pattern "?he" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "?he" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.PatternMatching ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the pattern "?he"; the first occurrence is "The" and the second occurrence is "the". Therefore, the variable ($)Indexes will be updated to the following:

[0, 31]

where 0 indicates the index of the first character of the matching "The" occurrence, and 31 indicates the index of the first character of the matching "the" occurrence.


Get Indexes of all occurrences matching the regex in Text To Remove

This example will get the indexes of all occurrences of text matching the regex "(fox|dog)" from "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Find ($)TextToFind, with value "(fox|dog)" ($)TextToFind is a variable of type String
Search Options ($)SearchOptions, with value SearchOptions.Regex ($)SearchOptions is a variable of type SearchOptions
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Indexes ($)Indexes, with no value ($)Indexes is a variable that will be set to an IList<Int32> value

Result

"The quick brown fox jumps over the lazy dog" contains two occurrences that match the regex "(fox|dog)"; the first occurrence is "fox" and the second and last occurrence is "dog". Therefore, the variable ($)Indexes will be updated to the following:

[16, 40]

where 16 indicates the index of the first character of the matching "fox" occurrence, and 40 indicates the index of the first character of the matching "dog" occurrence.


Properties

Text

The Text to get the Indexes of all occurrences of Text To Find from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Find

The Text To Find the Indexes of all occurrences of, in Text.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Search Options

Search Options can be specified to choose whether Text To Find should be interpreted as a ContainsText, PatternMatching or Regex search:

  • SearchOptions.ContainsText matches text exactly; as long as the Text contains the text specified in Text To Find it will be considered a match.
  • SearchOptions.PatternMatching allows wildcard text matching using Pattern Matching Syntax:
    • * wildcard character can be used to match 0 or more characters.
    • ? wildcard character can be used to match 0 or 1 character.
    • All other characters are treated as a literal character.
  • SearchOptions.Regex allows regex text matching using .Net Regex Syntax.

Please note that with SearchOptions.ContainsText overlapping matches are detected (e.g. searching for "aa" in "aaa" matches "aa" at index 0 and "aa" at index 1). With SearchOptions.Regex only "aa" at index 0 will be matched.

Data Type SearchOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value ContainsText

Comparison Type

The Comparison Type specifying the rules used to match Text To Find in Text.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Indexes

IList<Int32> containing the Indexes of the first character of each occurrence of Text To Find in Text.

If there are no occurrences of Text To Find in Text, the specified variable will be set to [-1].

For information about what an index is, please see Indexes.

Data Type IList<Int32>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Indexes with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).
Thrown when Search Options is not one of the specified SearchOptions types (e.g. (SearchOptions)10).
RegexMatchTimeoutException Thrown when Search Options is either SearchOptions.Regex or SearchOptions.PatternMatching and the execution time of the search exceeds 30 seconds.
RegexParsingFailedException Thrown when Search Options is SearchOptions.Regex and Text To Find is not a valid regex (e.g. ().

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null or empty Text

If Text is null or empty (i.e. ""), the variable specified in the Indexes property is set to [-1].

Null or empty Text To Find

If Text To Find is null or empty (i.e. ""), the variable specified in the Indexes property is set to [-1].

Text To Find not found

If Text To Find is not found in Text, the variable specified in the Indexes property is set to [-1].

Known Limitations

If Search Options is set to SearchOptions.Regex or SearchOptions.PatternMatching and Comparison Type is set to StringComparison.CurrentCulture, some characters such as æ that is equivalent to ae may not evaluate as equal.

6.3.20.8 - Get Length

Get the length of a text.

6.3.20.8.1 - Get Length

Gets the length of a given text.
Icon

Get Length

(Cortex.Blocks.Text.GetLength.GetLengthBlock)

Description

Gets the Length of a given Text.

Examples

Get the Length of a given Text

This example will get the length of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Length ($)Length, with no value ($)Length is a variable that will be set to an Int32

Result

Getting the length of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)Length being updated to the following:

26

Properties

Text

The Text to get the Length of.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Length

The Length of the Text (i.e. the number of characters it contains).

Data Type Int32
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Length with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Null or empty Text

If Text is null or empty (i.e. "") the variable specified in the Length property will be set to 0.

6.3.20.9 - Get Text

Get text from a given text.

6.3.20.9.1 - Get Text At Beginning

Gets a length of text from the beginning of a given text.
Icon

Get Text At Beginning

(Cortex.Blocks.Text.GetText.GetTextAtBeginningBlock)

Description

Gets a Length of text from the beginning of a given Text.

Examples

Get a Length of text from the beginning of a given Text

This example will get the first 3 characters from the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Length ($)Length, with value 3 ($)Length is a variable of type Int32
Text At Beginning ($)TextAtBeginning, with no value ($)TextAtBeginning is a variable that will be set to a String

Result

Getting the first 3 characters from the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)TextAtBeginning being updated to the following:

"ABC"

Properties

Text

The Text to get the Text At Beginning from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Length

The Length of text to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Text At Beginning

The Length of text at the beginning of Text.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextAtBeginning with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Length is greater than the length of Text.

Remarks

Negative Length

If Length is negative, the variable specified in the Text At Beginning property will be set to the value of Text.

Zero Length

If Length is 0, the variable specified in the Text At Beginning property will be set to empty (i.e. "").

6.3.20.9.2 - Get Text At End

Gets a length of text from the end of a given text.
Icon

Get Text At End

(Cortex.Blocks.Text.GetText.GetTextAtEndBlock)

Description

Gets a Length of text from the end of a given Text.

Examples

Get a Length of text from the end of a given Text

This example will get the last 3 characters from the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Length ($)Length, with value 3 ($)Length is a variable of type Int32
Text At End ($)TextAtEnd, with no value ($)TextAtEnd is a variable that will be set to a String

Result

Getting the last 3 characters from the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)TextAtEnd being updated to the following:

"XYZ"

Properties

Text

The Text to get the Text At End from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Length

The Length of text to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Text At End

The Length of text at the end of Text.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextAtEnd with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Length is greater than the length of Text.

Remarks

Negative Length

If Length is negative, the variable specified in the Text At End property will be set to the value of Text.

Zero Length

If Length is 0, the variable specified in the Text At End property will be set to empty (i.e. "").

6.3.20.9.3 - Get Text At Index

Gets a length of text at the specified index of a given text.
Icon

Get Text At Index

(Cortex.Blocks.Text.GetText.GetTextAtIndexBlock)

Description

Gets a Length of text at the specified Index of a given Text.

Examples

Get a Length of text at the specified Index of a given Text

This example will get 3 characters at index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Index ($)Index, with value 3 ($)Index is a variable of type Int32
Length ($)Length, with value 3 ($)Length is a variable of type Int32
Text At Index ($)TextAtIndex, with no value ($)TextAtIndex is a variable that will be set to a String

Result

"D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, getting 3 characters at (and including) index 3 results in the variable ($)TextAtIndex being updated to the following:

"DEF"

Properties

Text

The Text to get the Text At Index from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Index

The Index to get the text from. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Length

The Length of text to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Text At Index

The Length of text at the Index of Text.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextAtIndex with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Textis null or empty (i.e. "").
Thrown when Index is less than zero or greater than the length of Text - 1.
Thrown when Index + a positive Length is greater than the length of Text - 1.

Remarks

Negative Length

A negative Length can be used to get all text at and after the Index of Text.

Zero Length

If Length is 0, the variable specified in the Text At Index property will be set to empty (i.e. "").

Index is inclusive

The Index property is an inclusive index, which means the character at the index will be included in the retrieved text.

6.3.20.9.4 - Get Text Before Index

Gets a length of text before the specified index of a given text.
Icon

Get Text Before Index

(Cortex.Blocks.Text.GetText.GetTextBeforeIndexBlock)

Description

Gets a Length of text before the specified Index of a given Text.

Examples

Get a Length of text before the specified Index of a given Text

This example will get 3 characters before index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Index ($)Index, with value 3 ($)Index is a variable of type Int32
Length ($)Length, with value 3 ($)Length is a variable of type Int32
Text Before Index ($)TextBeforeIndex, with no value ($)TextBeforeIndex is a variable that will be set to a String

Result

"D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, getting 3 characters before index 3 results in the variable ($)TextBeforeIndex being updated to the following:

"ABC"

Properties

Text

The Text to get the Text Before Index from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Index

The Index to get the text before. This is an exclusive index, which means the character at the specified index won’t be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Length

The Length of text to get.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Text Before Index

The Length of text before the Index of Text.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextBeforeIndex with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Index is less than 1 or greater than the length of Text - 1.
Thrown when Index - a positive Length is less than 1.

Remarks

Negative Length

A negative Length can be used to get all text before the Index of Text.

Zero Length

If Length is 0, the variable specified in the Text Before Index property will be set to empty (i.e. "").

Index is exclusive

The Index property is an exclusive index, which means the character at the index will not be included in the retrieved text.

6.3.20.9.5 - Get Text Between Indexes

Gets text between the specified start index and end index of a given text.
Icon

Get Text Between Indexes

(Cortex.Blocks.Text.GetText.GetTextBetweenIndexesBlock)

Description

Gets text between the specified Start Index and End Index of a given Text.

Examples

Get text between the specified Start Index and End Index of a given Text

This example will get all characters between start index 0 and end index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Start Index ($)StartIndex, with value 0 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 3 ($)EndIndex is a variable of type Int32
Text Between Indexes ($)TextBetweenIndexes, with no value ($)TextBetweenIndexes is a variable that will be set to a String

Result

"A" is at index 0 and "D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, getting all characters between (and including) start index 0 and end index 3 results in the variable ($)TextBetweenIndexes being updated to the following:

"ABCD"

Get text where Start Index is greater than End Index

This example will get all characters between start index 3 and end index 0 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Start Index ($)StartIndex, with value 3 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 0 ($)EndIndex is a variable of type Int32
Text Between Indexes ($)TextBetweenIndexes, with no value ($)TextBetweenIndexes is a variable that will be set to a String

Result

In this example the start index 3 is greater than the end index 0. When this occurs, the block simply swaps the indexes before it processes the text.

Therefore, having start index 3 and end index 0 is the same as having start index 0 and end index 3.

"A" is at index 0 and "D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Therefore, getting all characters between (and including) start index 3 and end index 0, or start index 0 and end index 3, results in the variable ($)TextBetweenIndexes being updated to the following:

"ABCD"

Properties

Text

The Text to get the Text Between Indexes from.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Start Index

The Start Index used to get the text. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

End Index

The End Index used to get the text. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Text Between Indexes

The text between (and including) the Start Index and End Index of Text.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextBetweenIndexes with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Start Index or End Index is less than zero or greater than the length of Text - 1.

Remarks

Start Index and End Index are inclusive

The Start Index and End Index properties are both inclusive indexes, which means the characters at those indexes will be included in the retrieved text.

Start Index greater than End Index

Start Index can be greater than End Index. If this is the case, the values of the indexes will be swapped. See Example above.

6.3.20.10 - Is Text

Check if text is equal to another text, null, empty (i.e. ""), or whitespace (e.g. " ").

6.3.20.10.1 - Is Text Empty

Checks if text is empty (i.e. "").
Icon

Is Text Empty

(Cortex.Blocks.Text.IsText.IsTextEmptyBlock)

Description

Checks if Text is empty (i.e. "") .

For information about empty, please see Empty Text and Whitespace.

Examples

Text is empty

This example will check if "" is empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "" ($)Text is a variable of type String
Text Is Empty ($)TextIsEmpty, with no value ($)TextIsEmpty is a variable that will be set to a Boolean value

Result

"" is empty (i.e. ""), resulting in the variable ($)TextIsEmpty being updated to the following:

true

Text is null

This example will check if null is empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value null ($)Text is a variable of type String
Text Is Empty ($)TextIsEmpty, with no value ($)TextIsEmpty is a variable that will be set to a Boolean value

Result

null is not empty (i.e. ""), resulting in the variable ($)TextIsEmpty being updated to the following:

false

Text is whitespace

This example will check if " " is empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value " " ($)Text is a variable of type String
Text Is Empty ($)TextIsEmpty, with no value ($)TextIsEmpty is a variable that will be set to a Boolean value

Result

" " is not empty (i.e. ""), resulting in the variable ($)TextIsEmpty being updated to the following:

false

Text is not empty

This example will check if "The quick brown fox jumps over the lazy dog" is empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text Is Empty ($)TextIsEmpty, with no value ($)TextIsEmpty is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" is not empty (i.e. ""), resulting in the variable ($)TextIsEmpty being updated to the following:

false

Properties

Text

The Text to check is empty (i.e. "").

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text Is Empty

The result of the is empty check.

If the Text is empty (i.e. ""), the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsEmpty with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Null Text

If Text is null the variable specified in the Text Is Empty property will be set to false. See Example above.

Whitespace Text

If Text is whitespace (e.g. " ") the variable specified in the Text Is Empty property will be set to false. See Example above.

6.3.20.10.2 - Is Text Empty Or Whitespace

Checks if text is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).
Icon

Is Text Empty Or Whitespace

(Cortex.Blocks.Text.IsText.IsTextEmptyOrWhitespaceBlock)

Description

Checks if Text is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

For information about empty and whitespace, please see Empty Text and Whitespace.

Examples

Text is empty

This example will check if "" is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value "" ($)Text is a variable of type String
Text Is Empty Or Whitespace ($)TextIsEmptyOrWhitespace, with no value ($)TextIsEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

"" is empty (i.e. ""), resulting in the variable ($)TextIsEmptyOrWhitespace being updated to the following:

true

Text is whitespace

This example will check if " " is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value " " ($)Text is a variable of type String
Text Is Empty Or Whitespace ($)TextIsEmptyOrWhitespace, with no value ($)TextIsEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

" " is whitespace, resulting in the variable ($)TextIsEmptyOrWhitespace being updated to the following:

true

Text is null

This example will check if null is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value null ($)Text is a variable of type String
Text Is Empty Or Whitespace ($)TextIsEmptyOrWhitespace, with no value ($)TextIsEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

null is not empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters), resulting in the variable ($)TextIsEmptyOrWhitespace being updated to the following:

false

Text is not empty or whitespace

This example will check if "The quick brown fox jumps over the lazy dog" is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text Is Empty Or Whitespace ($)TextIsEmptyOrWhitespace, with no value ($)TextIsEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" is not empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters), resulting in the variable ($)TextIsEmptyOrWhitespace being updated to the following:

false

Properties

Text

The Text to check is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text Is Empty Or Whitespace

The result of the is empty or whitespace check.

If the Text is empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters), the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsEmptyOrWhitespace with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Null Text

If Text is null the variable specified in the Text Is Empty Or Whitespace property will be set to false. See Example above.

6.3.20.10.3 - Is Text Equal

Checks if a text is equal to another text.
Icon

Is Text Equal

(Cortex.Blocks.Text.IsText.IsTextEqualBlock)

Description

Checks if Text is equal to Text To Compare.

Examples

Text is equal to Text To Compare (Ordinal)

This example will check if "The quick brown fox jumps over the lazy dog" is equal to "The quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Compare ($)TextToCompare, with value "The quick brown fox jumps over the lazy dog" ($)TextToCompare is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Text Is Equal ($)TextIsEqual, with no value ($)TextIsEqual is a variable that will be set to a Boolean value

Result

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" is equal to "The quick brown fox jumps over the lazy dog", as they match exactly, including casing. Therefore, the variable ($)TextIsEqual will be updated to the following:

true

Text is not equal to Text To Compare (Ordinal)

This example will check if "The quick brown fox jumps over the lazy dog" is equal to "the quick brown fox jumps over the lazy dog".

It performs a case-sensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Compare ($)TextToCompare, with value "the quick brown fox jumps over the lazy dog" ($)TextToCompare is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.Ordinal ($)ComparisonType is a variable of type StringComparison
Text Is Equal ($)TextIsEqual, with no value ($)TextIsEqual is a variable that will be set to a Boolean value

Result

As this example is performing a case-sensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" is not equal to "the quick brown fox jumps over the lazy dog", as whilst the characters match exactly, the casing of the first "T" differs. Therefore, the variable ($)TextIsEqual will be updated to the following:

false

Text is equal to Text To Compare (Ordinal Ignore Case)

This example will check if "The quick brown fox jumps over the lazy dog" is equal to "the quick brown fox jumps over the lazy dog".

It performs a case-insensitive, culture-insensitive comparison of text.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text To Compare ($)TextToCompare, with value "the quick brown fox jumps over the lazy dog" ($)TextToCompare is a variable of type String
Comparison Type ($)ComparisonType, with value StringComparison.OrdinalIgnoreCase ($)ComparisonType is a variable of type StringComparison
Text Is Equal ($)TextIsEqual, with no value ($)TextIsEqual is a variable that will be set to a Boolean value

Result

As this example is performing a case-insensitive, culture-insensitive comparison of text, "The quick brown fox jumps over the lazy dog" is equal to "the quick brown fox jumps over the lazy dog", as the characters match exactly, and casing is not considered. Therefore, the variable ($)TextIsEqual will be updated to the following:

true

Properties

Text

The Text to check is equal to Text To Compare.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text To Compare

The Text To Compare if Text is equal to.

Data Type String
Property Type Input
Is Advanced false
Default Editor Expression
Default Value $@""

Comparison Type

The Comparison Type specifying the rules used to compare if Text is equal to Text To Compare.

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Data Type StringComparison
Property Type Input
Is Advanced true
Default Editor Literal
Default Value Ordinal

Text Is Equal

Boolean indicating whether Text is equal to Text To Compare.

If they are equal the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsEqual with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Comparison Type is not one of the specified StringComparison types (e.g. (StringComparison)10).

Remarks

Comparison Types

For information about the supported values for the Comparison Type property and examples of how it is determined whether two pieces of text match, please see Equality.

Null vs empty

If Text is null and Text To Compare is empty (i.e. ""), or vice versa, the variable specified in the Text Is Equal property is set to false, as null and "" are not equal.

6.3.20.10.4 - Is Text Null

Checks if text is null.
Icon

Is Text Null

(Cortex.Blocks.Text.IsText.IsTextNullBlock)

Description

Checks if Text is null.

For information about null, please see Null and Nullable Types.

Examples

Text is null

This example will check if null is null.

Properties

Property Value Notes
Text ($)Text, with value null ($)Text is a variable of type String
Text Is Null ($)TextIsNull, with no value ($)TextIsNull is a variable that will be set to a Boolean value

Result

null is null, resulting in the variable ($)TextIsNull being updated to the following:

true

Text is empty

This example will check if empty (i.e. "") is null.

Properties

Property Value Notes
Text ($)Text, with value "" ($)Text is a variable of type String
Text Is Null ($)TextIsNull, with no value ($)TextIsNull is a variable that will be set to a Boolean value

Result

Empty (i.e. "") is not null, resulting in the variable ($)TextIsNull being updated to the following:

false

Text is whitespace

This example will check if " " is null.

Properties

Property Value Notes
Text ($)Text, with value " " ($)Text is a variable of type String
Text Is Null ($)TextIsNull, with no value ($)TextIsNull is a variable that will be set to a Boolean value

Result

" " is not null, resulting in the variable ($)TextIsNull being updated to the following:

false

Text is not null

This example will check if "The quick brown fox jumps over the lazy dog" is null.

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text Is Null ($)TextIsNull, with no value ($)TextIsNull is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" is not null, resulting in the variable ($)TextIsNull being updated to the following:

false

Properties

Text

The Text to check is null.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text Is Null

The result of the is null check.

If the Text is null, the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsNull with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Empty Text

If Text is empty (i.e.. "") the variable specified in the Text Is Null property will be set to false. See Example above.

Whitespace Text

If Text is whitespace (e.g. " ") the variable specified in the Text Is Null property will be set to false. See Example above.

6.3.20.10.5 - Is Text Null Or Empty

Checks if text is null or empty (i.e. "").
Icon

Is Text Null Or Empty

(Cortex.Blocks.Text.IsText.IsTextNullOrEmptyBlock)

Description

Checks if Text is null or empty (i.e. "").

For information about null, please see Null and Nullable Types.

For information about empty, please see Empty Text and Whitespace.

Examples

Text is null

This example will check if null is null or empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value null ($)Text is a variable of type String
Text Is Null Or Empty ($)TextIsNullOrEmpty, with no value ($)TextIsNullOrEmpty is a variable that will be set to a Boolean value

Result

null is null, resulting in the variable ($)TextIsNullOrEmpty being updated to the following:

true

Text is empty

This example will check if "" is null or empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "" ($)Text is a variable of type String
Text Is Null Or Empty ($)TextIsNullOrEmpty, with no value ($)TextIsNullOrEmpty is a variable that will be set to a Boolean value

Result

"" is empty (i.e. ""), resulting in the variable ($)TextIsNullOrEmpty being updated to the following:

true

Text is whitespace

This example will check if " " is null or empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value " " ($)Text is a variable of type String
Text Is Null Or Empty ($)TextIsNullOrEmpty, with no value ($)TextIsNullOrEmpty is a variable that will be set to a Boolean value

Result

" " is not null or empty (i.e. ""), resulting in the variable ($)TextIsNullOrEmpty being updated to the following:

false

Text is not null or empty

This example will check if "The quick brown fox jumps over the lazy dog" is null or empty (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text Is Null Or Empty ($)TextIsNullOrEmpty, with no value ($)TextIsNullOrEmpty is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" is not null or empty (i.e. ""), resulting in the variable ($)TextIsNullOrEmpty being updated to the following:

false

Properties

Text

The Text to check is null or empty (i.e. "").

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text Is Null Or Empty

The result of the is null or empty check.

If the Text is null or empty (i.e. ""), the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsNullOrEmpty with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Whitespace Text

If Text is whitespace (e.g. " ") the variable specified in the Text Is Null Or Empty property will be set to false. See Example above.

6.3.20.10.6 - Is Text Null, Empty Or Whitespace

Checks if text is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).
Icon

Is Text Null, Empty Or Whitespace

(Cortex.Blocks.Text.IsText.IsTextNullEmptyOrWhitespaceBlock)

Description

Checks if Text is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

For information about null, please see Null and Nullable Types.

For information about empty and whitespace, please see Empty Text and Whitespace.

Examples

Text is null

This example will check if null is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value null ($)Text is a variable of type String
Text Is Null Empty Or Whitespace ($)TextIsNullEmptyOrWhitespace, with no value ($)TextIsNullEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

null is null, resulting in the variable ($)TextIsNullEmptyOrWhitespace being updated to the following:

true

Text is empty

This example will check if "" is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value "" ($)Text is a variable of type String
Text Is Null Empty Or Whitespace ($)TextIsNullEmptyOrWhitespace, with no value ($)TextIsNullEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

"" is empty (i.e. ""), resulting in the variable ($)TextIsNullEmptyOrWhitespace being updated to the following:

true

Text is whitespace

This example will check if " " is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value " " ($)Text is a variable of type String
Text Is Null Empty Or Whitespace ($)TextIsNullEmptyOrWhitespace, with no value ($)TextIsNullEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

" " is whitespace (i.e. space, tab, carriage return, line feed characters), resulting in the variable ($)TextIsNullEmptyOrWhitespace being updated to the following:

true

Text is not null, empty or whitespace

This example will check if "The quick brown fox jumps over the lazy dog" is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Properties

Property Value Notes
Text ($)Text, with value "The quick brown fox jumps over the lazy dog" ($)Text is a variable of type String
Text Is Null Empty Or Whitespace ($)TextIsNullEmptyOrWhitespace, with no value ($)TextIsNullEmptyOrWhitespace is a variable that will be set to a Boolean value

Result

"The quick brown fox jumps over the lazy dog" is not null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters), resulting in the variable ($)TextIsNullEmptyOrWhitespace being updated to the following:

false

Properties

Text

The Text to check is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters).

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Text Is Null Empty Or Whitespace

The result of the is null, empty or whitespace check.

If the Text is null, empty (i.e. "") or whitespace (i.e. space, tab, carriage return, line feed characters), the specified variable will be set to true, otherwise it will be set to false.

Data Type Boolean
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)TextIsNullEmptyOrWhitespace with no value

Exceptions

No exceptions are thrown by the block.

Remarks

No remarks for the block.

6.3.20.11 - Join Text

Join a set of values together (using a separator) to create text.

6.3.20.11.1 - Join Text

Joins a set of values together as text, using the given separator between each value.
Icon

Join Text

(Cortex.Blocks.Text.JoinText.JoinTextBlock`1)

Description

Joins a set of Values together as Text, using the given Separator between each value.

Examples

Join a set of String Values together with a pipe Separator

This example will join the set of String values, ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], together with a pipe separator (i.e. "|").

Properties

Property Value Notes
Values ($)Values, with value ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"] ($)Values is a variable of type IEnumerable<String>
Separator ($)Separator, with value "|" ($)Separator is a variable of type String
Text ($)Text, with no value ($)Text is a variable that will be set to a String

Result

Joining ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"] together as text with a pipe separator (i.e. "|"), results in the variable ($)Text being updated to the following:

"Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday"

Join a set of Int32 Values together with a comma Separator

This example will join the set of Int32 values, [1, 2, 3], together with a comma separator (i.e. ",").

Properties

Property Value Notes
Values ($)Values, with value [1, 2, 3] ($)Values is a variable of type IEnumerable<Int32>
Separator ($)Separator, with value "," ($)Separator is a variable of type String
Text ($)Text, with no value ($)Text is a variable that will be set to a String

Result

Each Int32 value will be converted to its text representation, by calling its ToString method (i.e. value.ToString()).

Joining [1, 2, 3] together as text with a comma separator (i.e. ","), results in the variable ($)Text being updated to the following:

"1,2,3"

Properties

Values

The set of Values to join together as Text.

Values will be joined together in the order they are defined.

Values can be any IEnumerable<TValue>, where TValue represents the type of values.

Each non-text value will be converted to its text representation, by calling its ToString method (i.e. value.ToString()).

Data Type IEnumerable<TValue>
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Values with no value

Separator

The text to use as a Separator between each of the Values.

Separator can contain zero or more characters.

The Separator is only included in the resultant Text if Values has more than 1 item.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value ,

Text

The resultant Text containing the specified Values converted to their text representation and separated by the given Separator.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Values is null.
OutOfMemoryException Thrown when the length of the resultant Text is longer than the maximum allowed length (2,147,483,647).

Remarks

Null or empty Separator

If Separator is null or empty (i.e. ""), an empty text (i.e. "") will be used as the separator.

Null or empty Value in Values

If any value in Values is null or empty (i.e. ""), an empty text (i.e. "") will be used as the value.

6.3.20.12 - Remove Text

Remove a length of text from a given text.

6.3.20.12.1 - Remove Text At Beginning

Removes a length of text from the beginning of a given text.
Icon

Remove Text At Beginning

(Cortex.Blocks.Text.RemoveText.RemoveTextAtBeginningBlock)

Description

Removes a Length of text from the beginning of a given Text.

Examples

Remove a Length of text from the beginning of a given Text

This example will remove the first 3 characters from the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Length ($)Length, with value 3 ($)Length is a variable of type Int32

Result

Removing the first 3 characters from the beginning of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)Text being updated to the following:

"DEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text to remove the Length of text from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Length

The Length of text to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Length is greater than the length of Text.

Remarks

Negative Length

If Length is negative, all text will be removed and the variable specified in the Text property will be set to empty (i.e. "").

Zero Length

If Length is 0, no text will be removed and the variable specified in the Text property will remain unchanged.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Length of text removed at the beginning and re-assigns it to the variable specified in the Text property.

6.3.20.12.2 - Remove Text At End

Removes a length of text from the end of a given text.
Icon

Remove Text At End

(Cortex.Blocks.Text.RemoveText.RemoveTextAtEndBlock)

Description

Removes a Length of text from the end of a given Text.

Examples

Remove a Length of text from the end of a given Text

This example will remove the last 3 characters from the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Length ($)Length, with value 3 ($)Length is a variable of type Int32

Result

Removing the last 3 characters from the end of "ABCDEFGHIJKLMNOPQRSTUVWXYZ" results in the variable ($)Text being updated to the following:

"ABCDEFGHIJKLMNOPQRSTUVW"

Properties

Text

The Text to remove the Length of text from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Length

The Length of text to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Length is greater than the length of Text.

Remarks

Negative Length

If Length is negative, all text will be removed and the variable specified in the Text property will be set to empty (i.e. "").

Zero Length

If Length is 0, no text will be removed and the variable specified in the Text property will remain unchanged.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Length of text removed at the end and re-assigns it to the variable specified in the Text property.

6.3.20.12.3 - Remove Text At Index

Removes a length of text at the specified index of a given text.
Icon

Remove Text At Index

(Cortex.Blocks.Text.RemoveText.RemoveTextAtIndexBlock)

Description

Removes a Length of text at the specified Index of a given Text.

Examples

Remove a Length of text at the specified Index of a given Text

This example will remove 3 characters at index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Index ($)Index, with value 3 ($)Index is a variable of type Int32
Length ($)Length, with value 3 ($)Length is a variable of type Int32

Result

"D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, removing 3 characters at (and including) index 3 results in the variable ($)Text being updated to the following:

"ABCGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text to remove the Length of text from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Index

The Index to remove the text from. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Length

The Length of text to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Index is less than zero or greater than the length of Text - 1.
Thrown when Index + a positive Length is greater than the length of Text - 1.

Remarks

Negative Length

A negative Length can be used to remove all text at and after the Index of Text.

Zero Length

If Length is 0, no text will be removed and the variable specified in the Text property will remain unchanged.

Index is inclusive

The Index property is an inclusive index, which means the character at the index will be included in the removed text.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Length of text removed at the specified Index and re-assigns it to the variable specified in the Text property.

6.3.20.12.4 - Remove Text Before Index

Removes a length of text before the specified index of a given text.
Icon

Remove Text Before Index

(Cortex.Blocks.Text.RemoveText.RemoveTextBeforeIndexBlock)

Description

Removes a Length of text before the specified Index of a given Text.

Examples

Remove a Length of text before the specified Index of a given Text

This example will remove 3 characters before index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Index ($)Index, with value 3 ($)Index is a variable of type Int32
Length ($)Length, with value 3 ($)Length is a variable of type Int32

Result

"D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, removing 3 characters before index 3 results in the variable ($)Text being updated to the following:

"DEFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text to remove the Length of text from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Index

The Index to remove the text before. This is an exclusive index, which means the character at the specified index won’t be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Length

The Length of text to remove.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value -1

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Index is less than 1 or greater than the length of Text - 1.
Thrown when Index - a positive Length is less than 1.

Remarks

Negative Length

A negative Length can be used to remove all text before the Index of Text.

Zero Length

If Length is 0, the variable specified in the Text property will be set to empty (i.e. "").

Index is exclusive

The Index property is an exclusive index, which means the character at the index will not be included in the removed text.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the Length of text removed before the specified Index and re-assigns it to the variable specified in the Text property.

6.3.20.12.5 - Remove Text Between Indexes

Removes text between the specified start index and end index of a given text.
Icon

Remove Text Between Indexes

(Cortex.Blocks.Text.RemoveText.RemoveTextBetweenIndexesBlock)

Description

Removes text between the specified Start Index and End Index of a given Text.

Examples

Remove text between the specified Start Index and End Index of a given Text

This example will remove all characters between start index 0 and end index 3 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Start Index ($)StartIndex, with value 0 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 3 ($)EndIndex is a variable of type Int32

Result

"A" is at index 0 and "D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ". Therefore, removing all characters between (and including) start index 0 and end index 3 results in the variable ($)Text being updated to the following:

"EFGHIJKLMNOPQRSTUVWXYZ"

Remove text where Start Index is greater than End Index

This example will remove all characters between start index 3 and end index 0 of "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Properties

Property Value Notes
Text ($)Text, with value "ABCDEFGHIJKLMNOPQRSTUVWXYZ" ($)Text is a variable of type String
Start Index ($)StartIndex, with value 3 ($)StartIndex is a variable of type Int32
End Index ($)EndIndex, with value 0 ($)EndIndex is a variable of type Int32

Result

In this example the start index 3 is greater than the end index 0. When this occurs, the block simply swaps the indexes before it processes the text.

Therefore, having start index 3 and end index 0 is the same as having start index 0 and end index 3.

"A" is at index 0 and "D" is at index 3 in "ABCDEFGHIJKLMNOPQRSTUVWXYZ".

Therefore, removing all characters between (and including) start index 3 and end index 0, or start index 0 and end index 3, results in the variable ($)Text being updated to the following:

"EFGHIJKLMNOPQRSTUVWXYZ"

Properties

Text

The Text to remove the text from.

Data Type String
Property Type InputOutput
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Start Index

The Start Index used to remove the text. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

End Index

The End Index used to remove the text. This is an inclusive index, which means the character at the specified index will be included.

For information about what an index is, please see Indexes.

Data Type Int32
Property Type Input
Is Advanced false
Default Editor Literal
Default Value 0

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyValueOutOfRangeException Thrown when Text is null or empty (i.e. "").
Thrown when Start Index or End Index is less than zero or greater than the length of Text - 1.

Remarks

Start Index and End Index are inclusive

The Start Index and End Index properties are both inclusive indexes, which means the characters at those indexes will be included in the removed text.

Start Index greater than End Index

Start Index can be greater than End Index. If this is the case, the values of the indexes will be swapped. See Example above.

Immutable String data type

The String data type used to represent Text is immutable, which means it is read-only and cannot be changed once created.

To overcome this, this block creates a new String which has the text removed between the specified Start Index and End Index, and re-assigns it to the variable specified in the Text property.

6.3.20.13 - Split Text

Split text (using a separator) into a list of values.

6.3.20.13.1 - Split Text

Splits text into a list of String values, using the given separator to determine where to split.
Icon

Split Text

(Cortex.Blocks.Text.SplitText.SplitTextBlock)

Description

Splits Text into a list of String Values, using the given Separator to determine where to split.

Split Options can be used to specify how to treat empty entries (i.e. "").

Examples

Split Text into a list of String Values using a pipe Separator

This example will split the text "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday" into a list of String values, using the pipe separator (i.e. "|") to determine where to split.

Properties

Property Value Notes
Text ($)Text, with value "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday" ($)Text is a variable of type String
Separator ($)Separator, with value "|" ($)Separator is a variable of type String
Split Options ($)SplitOptions, with value StringSplitOptions.None ($)SplitOptions is a variable of type StringSplitOptions
Values ($)Values, with no value ($)Values is a variable that will be set to an IList<String>

Result

Splitting "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday" using a pipe separator (i.e. "|"), results in the variable ($)Values being updated to the following:

["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

Split Text into a list of String Values using a comma Separator (removing empty entries)

This example will split the text "1,2,3,," into a list of String values, using the comma separator (i.e. ",") to determine where to split, and removing empty entries (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "1,2,3,," ($)Text is a variable of type String
Separator ($)Separator, with value "," ($)Separator is a variable of type String
Split Options ($)SplitOptions, with value StringSplitOptions.RemoveEmptyEntries ($)SplitOptions is a variable of type StringSplitOptions
Values ($)Values, with no value ($)Values is a variable that will be set to an IList<String>

Result

Splitting "1,2,3,," using a comma separator (i.e. ",") and removing the last 2 entries which are empty (i.e. ""), results in the variable ($)Values being updated to the following:

["1", "2", "3"]

Split Text into a list of String Values using a comma Separator (keeping empty entries)

This example will split the text "1,2,3,," into a list of String values, using the comma separator (i.e. ",") to determine where to split, and keeping empty entries (i.e. "").

Properties

Property Value Notes
Text ($)Text, with value "1,2,3,," ($)Text is a variable of type String
Separator ($)Separator, with value "," ($)Separator is a variable of type String
Split Options ($)SplitOptions, with value StringSplitOptions.None ($)SplitOptions is a variable of type StringSplitOptions
Values ($)Values, with no value ($)Values is a variable that will be set to an IList<String>

Result

Splitting "1,2,3,," using a comma separator (i.e. ",") and keeping the last 2 entries which are empty, results in the variable ($)Values being updated to the following:

["1", "2", "3", "", ""]

Properties

Text

The Text to split into Values using the given Separator.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Text with no value

Separator

The Separator used to determine where to split the Text into the Values.

Separator can contain zero or more characters.

The Separator is not included in the resultant Values.

Data Type String
Property Type Input
Is Advanced false
Default Editor Literal
Default Value ,

Split Options

Split Options used to specify how to treat empty entries (i.e. "").

Currently supported values for the Split Options property are:

  • StringSplitOptions.None (Default) - empty entries are included in Values.
  • StringSplitOptions.RemoveEmptyEntries - empty entries are excluded from Values.
Data Type StringSplitOptions
Property Type Input
Is Advanced true
Default Editor Literal
Default Value None

Values

The resultant Values containing an entry for each piece of split text in the order they are defined in Text.

Data Type IList<String>
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Values with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
ArgumentException Thrown when Split Options is not one of the specified StringSplitOptions types (e.g. (StringSplitOptions)10).

Remarks

Null or empty Text

If Text is null or empty (i.e. ""), then null or empty (i.e. "") respectively is added as the only entry to Values.

Null or empty Separator

If Separator is null or empty (i.e. ""), the value of the variable specified for the Text property is added as the only entry to Values.

Separator not found

If the Separator is not found in Text, the value of the variable specified for the Text property is added as the only entry to Values.

6.3.21 - Variables

Blocks related to working with Variables.

6.3.21.1 - Set Variable

Blocks that are used to set Variables.

6.3.21.1.1 - Set Variable

Sets a Variable to a given Value.
Icon

Set Variable

(Cortex.Blocks.Variables.SetVariable.SetVariableBlock`1)

Description

Sets a Variable to a given Value.

Any type of Value can be set, including Lists, Dictionaries, Structures etc.

If a Variable is set to the Value of another Variable that is a Reference Type then they will refer to the same instance. This means that if either Variable has new items added to it, items updated in it, or items removed from it, then both will be affected, please see Reference Types for more information.

If a Variable is set to the Value of another Variable that is a Value Type then they will refer to different instances. This means that if either Variable is updated, then only the updated variable will be affected, please see Value Types for more information.

Examples

Setting a Variable

This example will set a Variable to a list of [[1, 2, 3], [4, 5, 6]].

Properties

Property Value Notes
Value Value, with value [[1, 2, 3], [4, 5, 6]] The Value is of type List<List<Int32>>
Variable ($)Variable, with no value ($)Variable is a variable that will be set to the type of the value (i.e. List<List<Int32>>)

Result

Setting ($)Variable to [[1, 2, 3], [4, 5, 6]] results in the variable ($)Variable being updated to the following:

[
    [
        1, 
        2, 
        3
    ], 
    [
        4, 
        5, 
        6
    ]
]

Overwriting a Variable

This example will overwrite an existing Variable that has the text value "A text value", to a list value of [1, 2, 3].

Properties

Property Value Notes
Value Value, with value [1, 2, 3] The Value is of type List<Int32>
Variable ($)Variable, with value "A text value" ($)Variable is a variable that will be set to the type of the value (i.e. List<Int32>)

Result

Setting ($)Variable to [1, 2, 3] results in the variable ($)Variable being updated to the following:

[
    1, 
    2, 
    3
]

Note that ($)Variable is overwritten, any data previously stored within the variable will be lost.

Overwriting a Variable Property

This example will update the Items property within an existing Variable that has the text value "A text value", to a list of [1, 2, 3].

($)Variable has an initial value of:

{
    "Items": "A text value",
}

Properties

Property Value Notes
Value Value, with value [1, 2, 3] The Value is of type List<Int32>
Variable ($)Variable.Items, with value "A text value" ($)Variable.Items is a property within variable that will be set to the type of the value (i.e. List<Int32>)

Result

Setting the ($)Variable.Items property to [1, 2, 3] results in the ($)Variable being updated to the following:

{
    "Items": [ 
        1,
        2, 
        3 
    ]
}

Note that ($)Variable.Items is overwritten, any data previously stored within the property will be lost.


Properties

Value

The Value to set the Variable to.

A Variable can be set to any type of object, including Lists, Dictionaries, Structures etc.

Data Type TValue
Property Type Input
Is Advanced false
Default Editor Expression
Default Value No value (defaults to null)

Variable

The Variable that will be set to the Value.

If a Variable is set to the Value of another Variable that is a Reference Type then they will refer to the same instance. This means that if either Variable has new items added to it, items updated in it, or items removed from it, then both will be affected, please see Reference Types for more information.

If a Variable is set to the Value of another Variable that is a Value Type then they will refer to different instances. This means that if either Variable is updated, then only the updated variable will be affected, please see Value Types for more information.

Data Type TValue
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Variable with no value

Exceptions

No exceptions are thrown by the block.

Remarks

Initialising Variables

If the Set Variable block is used to set a Variable that is not initialised, the Variable will be initialised with the given Value when the block is run.

Overwriting Variables

If the Set Variable block is used to set a Variable that is already initialised and has a Value, the Variable will be overwritten with the new Value when the block is run.

A property of a Variable can also be overwritten, instead of the whole object. This is shown in the example above, Overwriting a Variable Property

Variable Scope

Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace’s scope are deleted.

The Set Variable block can only set a Variable that is accessible from its scope.

For information about variables and scope, please see Variables.

Null Value

If Value is not provided or is set to null, Variable will be set to null.

6.3.22 - Workspaces

Blocks used to organise flows and group related logic and actions together.

6.3.22.1 - End Workspace

Blocks that indicate the end of a workspace.

6.3.22.1.1 - End Workspace

Indicates the end of a workspace.
Icon

End Workspace

(Cortex.Blocks.Workspaces.EndWorkspace.EndWorkspaceBlock)

Description

Indicates the end of a workspace; when a flow execution reaches this block it will exit the workspace, and all variables declared in the scope of the workspace are deleted.

A workspace can contain any number of these blocks, and they can be placed anywhere in the workspace.

The block has no block specific properties, but it does have the Description property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block.

A breakpoint can be added to this block when debugging.

Examples

No examples for the block.

Properties

No properties for the block, other than the Description property that is common to all blocks.

Exceptions

No exceptions are thrown by the block.

Remarks

Workspace Scope

Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace’s scope are deleted.

For information about variables and scope, please see Variables.

6.3.22.2 - Start Workspace

Blocks that indicate the start of a workspace.

6.3.22.2.1 - Start Workspace

Indicates the start of a workspace.
Icon

Start Workspace

(Cortex.Blocks.Workspaces.StartWorkspace.StartWorkspaceBlock)

Description

Indicates the start of a workspace; when a flow execution reaches this block it will create a new scope for the workspace.

This is always the first block in a workspace. It cannot be deleted, and a workspace can only contain one of these blocks.

The block has no block specific properties, but it does have the Description property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block.

A breakpoint can be added to this block when debugging.

Examples

No examples for the block.

Properties

No properties for the block, other than the Description property that is common to all blocks.

Exceptions

No exceptions are thrown by the block.

Remarks

Workspace Scope

Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace’s scope are deleted.

For information about variables and scope, please see Variables.

6.3.22.3 - Workspace

Blocks that represent a new workspace.

6.3.22.3.1 - Workspace

Represents a new workspace.
Icon

Workspace

(Cortex.Blocks.Workspaces.Workspace.WorkspaceBlock)

Description

This block represents a new workspace; when a flow execution reaches this block it will move to the Start Workspace block within this block’s workspace; each workspace has its own scope.

The Workspace block can be used to organise block logic into smaller steps with distinct functions. When a new Workspace block is placed on a flow, it will contain a Start Workspace and End Workspace block within its workspace.

If a Workspace block is copied and pasted its workspace is also copied, along with all blocks and variables within its scope.

The block has no block specific properties, but it does have the Description property that is common to all blocks. This allows users to give each block a description; typically this will be left blank for this block. Any description given will become the name for this block’s scope

A breakpoint can be added to this block when debugging.

Examples

No examples for the block.

Properties

No properties for the block, other than the Description property that is common to all blocks, and the Block Timeout property that is common to most blocks.

Exceptions

No exceptions are thrown by the block.

Remarks

Block Restrictions

A workspace can contain any number of blocks. The only restrictions within a workspace are that there can only be one Start Workspace block and one Handle Workspace Exception block within a workspace.

Starting a flow that contains more than one of the restricted blocks within a workspace will cause a Validation Error to occur.

Unhandled Exceptions

If an exception thrown by a block is not handled by any connected Handle Block Exception blocks, it will be passed to the Handle Workspace Exception block on the same workspace.

If the workspace does not contain a Handle Workspace Exception block it will be rethrown by the Workspace block the workspace belongs to.

This process repeats until:

If an exception occurs within the workspace of the Handle Flow Exception block and is not handled, the flow will end with a status of Error.

Icon

For more information about chaining of exception handling blocks and passing of exceptions, please see Exception Handling.

Workspace Scope

Each workspace has its own scope; as a result, variables can be defined that only exist and are accessible in this workspace and any of its sub-workspaces. On exiting a workspace any variables defined for the workspace’s scope are deleted.

For information about variables and scope, please see Variables.

6.3.23 - Xml

Blocks related to working with Xml.

6.3.23.1 - Convert Xml

Convert xml to and from other data types.

6.3.23.1.1 - Convert Structure To Xml

Converts a Structure To Xml.
Icon

Convert Structure To Xml

(Cortex.Blocks.Xml.ConvertXml.ConvertStructureToXmlBlock)

Description

Converts a Structure to Xml.

Each top-level Key will be converted using the following rules:

  • Keys become Nodes
  • Items become the values of the corresponding node.

Each inner key will be converted using the following rules:

  • Inner keys become inner nodes within their parent node.
  • Items of inner keys become the values of the corresponding inner nodes.

For example:

"topLevelNode": { 
    "innerNode" : "innerNodeValue" 
}

will be converted into:

@"<topLevelNode>
    <innerNode>innerNodeValue</innerNode>
</topLevelNode>"

Examples

Convert a Structure To Xml

This example will convert the Structure below to its Xml representation.

{
    "node1" : "1",
    "node2" : "2",
    "node3" : "3"
}

Properties

Property Value Notes
Structure ($)Structure, with value {{ "node1" : "1"}, {"node2" : "2"}, {"node3" : "3"}} ($)Structure is a variable of type Structure
Xml ($)Xml, with no value ($)Xml is a variable that will be set to a String value.

Result

Converting:

{
    "node1" : "1",
    "node2" : "2",
    "node3" : "3"
}

to Xml results in the variable ($)Xml being updated to the following:

@"<Cortex_DataTypes_Dictionaries_Structure>
    <node1>1</node1>
    <node2>2</node2>
    <node3>3</node3>
</Cortex_DataTypes_Dictionaries_Structure>"
  • The "Cortex_DataTypes_Dictionaries_Structure" root node is added as there is no single top-level key.
  • The "node1" Key is converted into a child node of "Cortex_DataTypes_Dictionaries_Structure" with its corresponding Item as the value.
  • The "node2" Key is converted into a child node of "Cortex_DataTypes_Dictionaries_Structure" with its corresponding Item as the value.
  • The "node3" Key is converted into a child node of "Cortex_DataTypes_Dictionaries_Structure" with its corresponding Item as the value.

Convert a Complex Structure to Xml

This example will convert the Structure below to its Xml representation. This scenario is unlikely unless Xml has been converted to a Structure and is being Round-Tripped.

{
    "topLevelKey": {
        "@topLevelAttribute" : "exampleAttribute",
        "innerKey" : {
            "@innerNodeAttribute" : "exampleInnerNodeAttribute",
            "nestedKey": "nested key text",
            "#text": "inner key text"
        },
        "id": [
            1, 
            2, 
            3
        ],
    }
}

Properties

Property Value Notes
Structure ($)Structure, with value"{"topLevelNode": {"@topLevelAttribute" : "exampleAttribute", "innerNode" : { "@innerNodeAttribute" : "exampleInnerNodeAttribute", "nestedNode": "nested node text", "#text": "inner node text" }, "id": [ 1, 2, 3 ], } }" ($)Structure is a variable of type Structure
Xml ($)Xml, with no value ($)Xml is a variable that will be set to a String value.

Result

Converting:

{
    "topLevelKey": {
        "@topLevelAttribute" : "exampleAttribute",
        "innerKey" : {
            "@innerNodeAttribute" : "exampleInnerNodeAttribute",
            "nestedKey": "nested key text",
            "#text": "inner key text"
        },
        "id": [
            1, 
            2, 
            3
        ],
    }
}

to Xml results in the variable ($)Xml being updated to the following:

@"<topLevelKey topLevelAttribute=""exampleAttribute"">
    <innerKey innerNodeAttribute=""exampleInnerNodeAttribute"">
        <nestedKey>nested key text</nestedKey>
        inner key text
    </innerKey>
    <id>1</id>
    <id>2</id>
    <id>3</id>
</topLevelKey>"
  • The key "topLevelKey" is converted into the "topLevelKey" node.
  • The key "@topLevelAttribute" is converted into the "topLevelAttribute" attribute with its corresponding item as the value.
  • The key "innerKey" is converted into the "innerKey" node.
  • The key "@innerNodeAttribute" is converted into the "innerNodeAttribute" attribute with its corresponding item as the value.
  • The key "nestedKey" is converted into the "nestedKey" node with its corresponding item as the value.
  • The key "#text" is converted into the value of the "innerKey" key with its corresponding item as the value.
  • The key "id" is converted into three "id" nodes with each corresponding item as their values.

Properties

Structure

The Structure to convert into Xml.

Data Type Structure
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Structure with no value

Xml

The Xml that has been converted from the Structure.

Data Type String
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Xml with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Structure is null.
PropertyEmptyException Thrown when Structure does not contain any items.
XmlSerializationException Thrown when Structure has a key that is an empty string.
Thrown when the Structure includes an xml declaration key (e.g. "?xml" can only accept the following attributes: "@version", "@encoding" and "@standalone".) or a document type definition key (e.g. "!DOCTYPE" can only accept the following attributes: "@name", "@public", "@system" and "@internalSubset").
Thrown when the Structure includes an xml declaration key (e.g. "?xml") with an attribute that has an invalid Basic Data Type. (e.g. Key: "@version", Value: false, where "@version" must be a numeric value).
Thrown when the Structure includes a document type definition key (e.g. "!DOCTYPE") that has an attribute with an invalid Basic Data Type. (e.g. Key: "@name", Value: 22, where "@name" must be a text value).
Thrown when the Structure includes an attribute key with a Complex Data Type as a value. (e.g. Key: "@name", Value: new UserCredentials{...}).

Remarks

Attributes

If a Node requires an attribute, the attribute is defined by a Key where the key is the attribute name with an "@" before it and the Item is the attribute data, for example:

{
    "node": {
        "@attribute": "Attribute Value",
        "innernode": "Inner Node Value"
    }
}

The Xml example above would be converted to the following Structure

@"<node attribute="Attribute Value">
    <innerNode>Inner Node Value</innerNode>
</node>"

Basic Data Types within Attribute Keys

Attribute keys may only have Basic Data Types as shown in the example below. An XmlSerializationException will be thrown if a Complex Data Type is used as an attribute key.

{
    "node": {
        "@validAttribute": "Attribute Value",
        "@invalidAttribute": new ComplexDataType("Invalid"),
    }
}

Key Restrictions

An Xml declaration key (e.g. "?xml") can only accept the following attributes: "@version", "@encoding" and "@standalone".

A document type definition key (e.g. "!DOCTYPE") can only accept the following attributes: "@name", "@public", "@system" and "@internalSubset".

"$id", "$ref", "$type", "$value" and "values" are reserved words and should not be used as keys.

Text Nodes

If a key contains a structure as its item, the inner keys are converted into Nodes with their corresponding items as the values. The key "#text" is converted into value of its parent node.

{
    "node": {
        "innerNode": {
            "@attrubute": "attributeValue",
            "#text": "Inner Node Value"
        },
        "#text": "Node Value"
    }
}

The Structure example above would be converted to the following Xml.

@"<node>
    <innerNode attribute="attributeValue">
        Inner Node Value
    </innerNode>
    Node Value
</node>"

Duplicate Nodes at the Same Level

If there are multiple duplicate nodes at the same level, they are defined using a Key where the key is the duplicated node name and the Item is a list of each of the corresponding duplicate node’s values, for example:

{
    "node": {
        "duplicateNode": ["First Duplicate Node", "Second Duplicate Node"],
        "distinctNode": "Distinct Node"
    }
}

The Structure example above would be converted to the following Xml.

@"<node>
    <duplicateNode>
        First Duplicate Node
    </duplicateNode>
    <duplicateNode>
        Second Duplicate Node
    </duplicateNode>
    <distinctNode>
        Distinct Node
    </distinctNode>
</node>"

Using Non-Alphanumeric Symbols within Node Names

Any non-alphanumeric symbol (i.e. symbols that are not "0" to "9", "a" to "z", or "A" to "Z") will be converted to their respective Unicode values when used within a Key. For example, "!" and "&" are both non-alphanumeric symbols and would be converted to "x0021" and "x0026" respectively.

For more information on characters and their Unicode values please see Character Sets

Round-tripping

It should be possible to pass the Xml created by this block to the Convert Xml To Structure block, and then pass the Structure created by the Convert Xml To Structure block back to this block, as long all values within the Xml are Strings; this is called round-tripping.

<Cortex_DataTypes_Dictionaries_Structure> Node

"<Cortex_DataTypes_Dictionaries_Structure>" is added as a root node when the Structure has more than one top-level key to ensure that valid Xml is produced.

{
    "node1" : "1",
    "node2" : "2",
    "node3" : "3"
}

The Xml example above would be converted to the following Structure.

@"<Cortex_DataTypes_Dictionaries_Structure>
    <node1>1</node1>
    <node2>2</node2>
    <node3>3</node3>
</Cortex_DataTypes_Dictionaries_Structure>"

6.3.23.1.2 - Convert Xml To Structure

Converts Xml to a Structure.
Icon

Convert Xml To Structure

(Cortex.Blocks.Xml.ConvertXml.ConvertXmlToStructureBlock)

Description

Converts Xml to a Structure.

Each top-level Node will be converted using the following rules:

  • Node names become Keys
  • Node values become Items

Each inner Node will be converted using the following rules:

  • Inner node names become Keys within the top-level node’s Item
  • Inner node values become the corresponding Item for their Key

For example:

@"<topLevelNode>
    <innerNode>innerNodeValue</innerNode>
</topLevelNode>"

will be converted into:

"topLevelNode": { 
    "innerNode" : "innerNodeValue" 
}

Examples

Convert Xml to a Structure

This example will convert the Xml below to its Structure representation.

@"<topLevelNode topLevelAttribute=""exampleAttribute"">
    <innerNode innerNodeAttribute=""exampleInnerNodeAttribute"">
        <nestedNode>nested node text</nestedNode>
        inner node text
    </innerNode>
    <id>1</id>
    <id>2</id>
    <id>3</id>
</topLevelNode>"

Properties

Property Value Notes
Xml ($)Xml, with value "<topLevelNode topLevelAttribute=""exampleAttribute""><innerNode innerNodeAttribute=""exampleInnerNodeAttribute""><nestedNode>nested node text</nestedNode>inner node text</innerNode><id>1</id><id>2</id><id>3</id></topLevelNode>" ($)Xml is a variable of type String
Structure ($)Structure, with no value ($)Structure is a variable that will be set to a Structure value

Result

Converting:

@"<topLevelNode topLevelAttribute=""exampleAttribute"">
    <innerNode innerNodeAttribute=""exampleInnerNodeAttribute"">
        <nestedNode>nested node text</nestedNode>
        inner node text
    </innerNode>
    <id>1</id>
    <id>2</id>
    <id>3</id>
</topLevelNode>"

to a Structure results in the variable ($)Structure being updated to the following:

{
    "topLevelNode": {
        "@topLevelAttribute" : "exampleAttribute",
        "innerNode" : {
            "@innerNodeAttribute" : "exampleInnerNodeAttribute",
            "nestedNode": "nested node text",
            "#text": "inner node text"
        },
        "id": [
            1, 
            2, 
            3
        ],
    }
}
  • The node "topLevelNode" is converted into the "topLevelNode" key.
  • The attribute "topLevelAttribute" is converted into the "@topLevelAttribute" key with its corresponding value as the item.
  • The node "innerNode" is converted into the "innerNode" key.
  • The attribute "innerNodeAttribute" is converted into the "@innerNodeAttribute" key with its corresponding value as the item.
  • The node "nestedNode" is converted into the "nestedNode" key with its corresponding value as the item.
  • The value of "innerNode" is converted into the "#text" key with its corresponding value as the item.
  • The three "id" nodes are converted into a single "id" key with each corresponding value being an entry of the item list.

Convert Round-tripped Xml to a Structure

This example will convert the Xml below to its Structure representation. This example will only occur when a Structure is Converted to Xml using the Convert Structure To Xml block and is then converted again using this block. This is called Round-Tripping.

Properties

Property Value Notes
Xml ($)Xml, with value "<Cortex_DataTypes_Dictionaries_Structure><node1>1</node1><node2>2</node2><node3>3</node3></Cortex_DataTypes_Dictionaries_Structure>" ($)Xml is a variable of type String
Structure ($)Structure, with no value ($)Structure is a variable that will be set to a Structure value

Result

Converting:

@"<Cortex_DataTypes_Dictionaries_Structure>
    <node1>1</node1>
    <node2>2</node2>
    <node3>3</node3>
</Cortex_DataTypes_Dictionaries_Structure>"

to a Structure results in the variable ($)Structure being updated to the following:

{
    "node1" : "1",
    "node2" : "2",
    "node3" : "3"
}
  • The "Cortex_DataTypes_Dictionaries_Structure" root node is removed and the child nodes are all at the root level.
  • The "node1" Node is converted into a Key of "node1" with its corresponding value as the Item.
  • The "node2" Node is converted into a Key of "node2" with its corresponding value as the Item.
  • The "node3" Node is converted into a Key of "node3" with its corresponding value as the Item.

Properties

Xml

The Xml to convert into a Structure.

Data Type String
Property Type Input
Is Advanced false
Default Editor Variable
Default Value ($)Xml with no value

Structure

The Structure that has been converted from the Xml.

Data Type Structure
Property Type Output
Is Advanced false
Default Editor Variable
Default Value ($)Structure with no value

Exceptions

The exceptions thrown by the block can be found below:

Name Description
PropertyNullException Thrown when Xml is null.
PropertyEmptyException Thrown when Xml is empty (i.e. "").
XmlSerializationException Thrown when the Xml is not valid (i.e the Xml contains an ampersand symbol or is missing a root node).

Remarks

Attributes

If a Node has an attribute, the attribute is converted to a Key where the key is the attribute name with an "@" before it and the value is the attribute data, for example:

@"<node attribute="Attribute Value">
    <innerNode>Inner Node Value</innerNode>
</node>"

The Xml example above would be converted to the following Structure

{
    "node": {
        "@attribute": "Attribute Value",
        "innernode": "Inner Node Value"
    }
}

Text Nodes

If a node contains a value and inner nodes or attributes, the inner nodes and attributes are converted into Keys with their corresponding values as the Items. The value of the node is converted into the "#text" key with its value as the item.

@"<node>
    <innerNode attribute="attributeValue">
        Inner Node Value
    </innerNode>
    Node Value
</node>"

The Xml example above would be converted to the following Structure.

{
    "node": {
        "innerNode": {
            "@attrubute": "attributeValue",
            "#text": "Inner Node Value"
        },
        "#text": "Node Value"
    }
}

Duplicate Nodes at the Same Level

If a node contains duplicate nodes at the same level, they are converted into a Key where the key is the duplicated node name and the Item is a list of each of the corresponding duplicate node’s values, for example:

@"<node>
    <duplicateNode>
        First Duplicate Node
    </duplicateNode>
    <duplicateNode>
        Second Duplicate Node
    </duplicateNode>
    <distinctNode>
        Distinct Node
    </distinctNode>
</node>"

The Xml example above would be converted to the following Structure.

{
    "node": {
        "duplicateNode": ["First Duplicate Node", "Second Duplicate Node"],
        "distinctNode": "Distinct Node"
    }
}

Using Non-Alphanumeric Symbols within Node Names

Any non-alphanumeric symbol (i.e. symbols that are not "0" to "9", "a" to "z", or "A" to "Z") will be converted to their respective Unicode values when used within a node name. For example, "!" and "&" are both non-alphanumeric symbols and would be converted to "x0021" and "x0026" respectively.

For more information on characters and their Unicode values please see Character Sets

Round-tripping

It should be possible to pass the Structure created by this block to the Convert Structure To Xml block, and then pass the Xml created by the Convert Structure To Xml block back to this block, as long all values within the Xml are Strings; this is called round-tripping.

<Cortex_DataTypes_Dictionaries_Structure> Node

The Convert Structure To Xml adds "<Cortex_DataTypes_Dictionaries_Structure>" as a root node when the structure has more than one top-level key to ensure that valid Xml is produced.

When the "<Cortex_DataTypes_Dictionaries_Structure>" root node is converted from Xml to a Structure the root node is removed and any inner nodes become the top-level keys.

@"<Cortex_DataTypes_Dictionaries_Structure>
    <node1>1</node1>
    <node2>2</node2>
    <node3>3</node3>
</Cortex_DataTypes_Dictionaries_Structure>"

The Xml example above would be converted to the following Structure.

{
    "node1" : "1",
    "node2" : "2",
    "node3" : "3"
}

This example will only occur when a Structure is Converted to Xml and is then converted again using this block. This is called Round-Tripping.

6.4 - Data Types

This section includes all reference documentation for data types.

6.4.1 - All

Data types used to represent all other data types.

6.4.1.1 - dynamic

Any data type can be used where a dynamic data type is required. dynamic data type is identical to the Object data type, except for one difference; dynamic data types do not need to be explicitly cast to other data types to be used, whereas Object data types do.

dynamic

Summary

Any data type can be used where a dynamic data type is required.

dynamic data type is identical to the Object data type, except for one difference; dynamic data types do not need to be explicitly cast to other data types to be used, whereas Object data types do.

Category: All
Name: dynamic
Full Name: N/A
Alias: N/A
Description: Any data type can be used where a dynamic data type is required. dynamic data type is identical to the Object data type, except for one difference; dynamic data types do not need to be explicitly cast to other data types to be used, whereas Object data types do.
Size: Varies
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Remarks

When is the dynamic Data Type Used?

The dynamic data type is only likely to be encountered in the following circumstances:

  • An Input or InputOutput property of a Block can accept any data type
  • An Output property of a Block can return any data type
  • A Collection that contains different data types (e.g. [1, "Text", true]) is saved to a Variable

Also note, in these circumstances it is more likely to encounter the dynamic data type, rather than Object. See Object vs dynamic for more information.

Object vs dynamic

Object and dynamic data types are identical, except for one difference:

  • Once a variable contains an Object data type, if it needs to be used as its original data type it must be cast back to that data type (e.g. (Int32)($)ObjectVariableContainingAnInteger); a dynamic data type does not.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is dynamic.
  • The Literal Editor is not available for Input properties where the data type is dynamic.
  • The Variable Editor is available for InputOutput and Output properties where the data type is dynamic.

Known Limitations

None

See Also

None

External Documentation

6.4.1.2 - Object

Any data type can be used where an Object data type is required, as all data types derive from Object.

Object

(System.Object)

Summary

Any data type can be used where an Object data type is required, as all data types derive from Object.

Object data type is identical to the dynamic data type, except for one difference; dynamic data types do not need to be explicitly cast to other data types to be used, whereas Object data types do.

Category: All
Name: Object
Full Name: System.Object
Alias: object
Description: Any data type can be used where an Object data type is required, as all data types derive from Object. Object data type is identical to the dynamic data type, except for one difference; dynamic data types do not need to be explicitly cast to other data types to be used, whereas Object data types do.
Size: Varies
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Remarks

When is the Object Data Type Used?

The Object data type is only likely to be encountered in the following circumstances:

  • An Input or InputOutput property of a Block can accept any data type
  • An Output property of a Block can return any data type
  • A Collection that contains different data types (e.g. [1, "Text", true]) is saved to a Variable

Also note, in these circumstances it is more likely to encounter the dynamic data type, rather than Object. See Object vs dynamic for more information.

It is also highly unlikely that you will need to create an Object; typically you will create and work with other data types such as String or Int32 that derive from Object. However, if ever required you can create a new object using the following expression:

new Object()

Object vs dynamic

Object and dynamic data types are identical, except for one difference:

  • Once a variable contains an Object data type, if it needs to be used as its original data type it must be cast back to that data type (e.g. (Int32)($)ObjectVariableContainingAnInteger); a dynamic data type does not.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Object.
  • The Literal Editor is not available for Input properties where the data type is Object.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Object.

Known Limitations

None

See Also

None

External Documentation

6.4.2 - Collections

Data types used for working with collections such as Lists, Dictionaries and Structures.

6.4.2.1 - Array

Any data type representing an array of items. The type of items that can be contained in the array depend upon the type of the array. Common examples include arrays of strings and integers (i.e. String[] and Int32[]).

Array

(System.Array)

Summary

Any data type representing an array of items.

The type of items that can be contained in the array depend upon the type of the array.

Common examples include arrays of strings and integers (i.e. String[] and Int32[]); for more see Most Common Array Data Types.

Arrays are very similar to Lists, but have some key differences, such as they are a fixed size and cannot be added to, or deleted from. For more information about the differences between Arrays and Lists, and when to use each of them see Arrays vs Lists.

Category: Collections
Name: Array
Full Name: System.Array
Alias: N/A
Description: Any data type representing an array of items. The type of items that can be contained in the array depend upon the type of the array.
Size: Varies
Default Value: null
Can be used as: IEnumerable, Object, dynamic
Can be cast to: N/A

Remarks

Most Common Array Data Types

Any of the following data types can be used where an Array is required:

  • Object[] - an array containing Object items
  • String[] - an array containing String items
  • Boolean[] - an array containing Boolean items
  • Int16[] - an array containing Int16 items
  • Int32[] - an array containing Int32 items
  • Int64[] - an array containing Int64 items
  • Single[] - an array containing Single items
  • Double[] - an array containing Double items

Create an Array

The following table shows some of the ways that an Array can be created.

Method Example Result Editor Support Notes
Use an explicit Array expression new Object[] {} [] Expression Object[] containing zero items
new String[] { "Some Text" } ["Some Text"] Expression String[] containing one String item
new Boolean[] { true, false } [true, false] Expression Boolean[] containing two Boolean items
new Int32[] { 1, 2, 3 } [1, 2, 3] Expression Int32[] containing three Int32 items
new Object[] { "Some Text", true, 1 } ["Some Text", true, 1] Expression Object[] containing a String item, a Boolean item and an Int32 item
Use an implicit Array expression new [] { "Some Text" } ["Some Text"] Expression String[] containing one String item. Implicit arrays must only contain a single data type
new [] { true, false } [true, false] Expression Boolean[] containing two Boolean items
new [] { 1, 2, 3 } [1, 2, 3] Expression Int32[] containing three Int32 items

Convert Array to Text

The following table shows some of the ways that an Array can be converted to text.

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has an Object[] value of ["Some Text", true, 1] "[\r\n \"Some Text\",\r\n true,\r\n 1\r\n]" N/A See Convert Object To Json

Property Editor Support

Currently no Input, InputOutput or Output properties require the Array data type.

Known Limitations

None

See Also

External Documentation

6.4.2.2 - Dictionary<TKey, TItem>

Used to represent a collection of key/item pairs. TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key.

Dictionary<TKey, TItem>

(System.Collections.Generic.Dictionary<TKey, TItem>)

Summary

The Dictionary<TKey, TItem> data type is used to represent a collection of key/item pairs.

TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key.

Category: Collections
Name: Dictionary<TKey, TItem>
Full Name: System.Collections.Generic.Dictionary<TKey, TItem>
Alias: N/A
Description: A collection of key/item pairs. TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key.
Size: Varies
Default Value: null
Can be used as: IDictionary<TKey, TItem>, IEnumerable, Object, dynamic
IEnumerable<KeyValuePair<TKey, TItem>> (e.g. where Dictionary<TKey, TItem> is Dictionary<String, Int32> and IEnumerable<KeyValuePair<TKey, TItem>> is IEnumerable<KeyValuePair<String, Int32>>)
Can be cast to: N/A

Remarks

Create a Dictionary<TKey, TItem>

The following table shows some of the ways that a Dictionary<TKey, TItem> can be created.

Method Example Result Editor Support Notes
Use a Dictionary<TKey, TItem> expression new Dictionary<String, dynamic>() {} Expression Dictionary<String, dynamic> containing zero items
new Dictionary<String, String>() { { "StringKey1", "StringValue" } } { "StringKey1": "StringValue" } Expression Dictionary<String, String> containing one String item with a String key
new Dictionary<String, Boolean>() { { "StringKey1", true }, { "StringKey2", false } } { "StringKey1": true, "StringKey2": false } Expression Dictionary<String, Boolean> containing two Boolean items with String keys
new Dictionary<String, Int32>() { { "StringKey1", 1 }, { "StringKey2", 2 }, { "StringKey3", 3 } } { "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 } Expression Dictionary<String, Int32> containing three Int32 item with String keys
new Dictionary<String, dynamic>() { { "StringKey1", "StringValue" }, { "StringKey2", true }, { "StringKey3", 1 } } { "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } Expression Dictionary<String, dynamic> containing a String item, a Boolean item and an Int32 item with String keys

Convert Dictionary<TKey, TItem> to Text

The following table shows some of the ways that a Dictionary<TKey, TItem> can be converted to text.

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a Dictionary<String, dynamic> value of { "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } "{\r\n \"StringKey1\": \"StringValue\",\r\n \"StringKey2\": true,\r\n \"StringKey3\": 1\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Dictionary<TKey, TItem>.
  • The Literal Editor is not available for Input properties where the data type is Dictionary<TKey, TItem>.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Dictionary<TKey, TItem>.

Known Limitations

  • Currently, only certain data types can be used for TKey. These include, but not limited to:
    • String
    • Int32
    • Double
    • Boolean
    • DateTimeOffset
  • If the data type of TKey is anything other than a String, when viewing the Dictionary<TKey, TItem> in Gateway the key value will be displayed as its ToString() representation (e.g. an Int32 key value of 1 will be displayed as "1" instead of 1).

See Also

External Documentation

6.4.2.3 - IDictionary<TKey, TItem>

Any data type representing a collection of key/item pairs. TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key. Dictionary<TKey, TItem> is the most common example.

IDictionary<TKey, TItem>

(System.Collections.Generic.IDictionary<TKey, TItem>)

Summary

Any data type representing a collection of key/item pairs.

TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key.

Dictionary<TKey, TItem> is the most common example.

Category: Collections
Name: IDictionary<TKey, TItem>
Full Name: System.Collections.Generic.IDictionary<TKey, TItem>
Alias: N/A
Description: Any data type representing a collection of key/item pairs. TKey indicates the data type of the keys used to access the items contained in the collection. TItem indicates the data type of the items contained in the collection. Each TItem can be individually accessed by a key.
Size: Varies
Default Value: null
Can be used as: IEnumerable, Object, dynamic
IEnumerable<KeyValuePair<TKey, TItem>> (e.g. where IDictionary<TKey, TItem> is IDictionary<String, Int32> and IEnumerable<KeyValuePair<TKey, TItem>> is IEnumerable<KeyValuePair<String, Int32>>)
Can be cast to: N/A

Remarks

Most Common IDictionary<TKey, TItem> Data Types

Any of the following data types can be used where an IDictionary<TKey, TItem> is required:

Create an IDictionary<TKey, TItem>

For some of the ways that an IDictionary<TKey, TItem> can be created, please see each of the IDictionary<TKey, TItem> data types:

Convert IDictionary<TKey, TItem> to Text

For some of the ways that an IDictionary<TKey, TItem> can be converted to text, please see each of the IDictionary<TKey, TItem> data types:

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is IDictionary<TKey, TItem>.
  • The Literal Editor is not available for Input properties where the data type is IDictionary<TKey, TItem>.
  • The Variable Editor is available for InputOutput and Output properties where the data type is IDictionary<TKey, TItem>.

Known Limitations

  • Currently, only certain data types can be used for TKey. These include, but not limited to:
    • String
    • Int32
    • Double
    • Boolean
    • DateTimeOffset
  • If the data type of TKey is anything other than a String, when viewing the IDictionary<TKey, TItem> in Gateway the key value will be displayed as its ToString() representation (e.g. an Int32 key value of 1 will be displayed as "1" instead of 1).

See Also

External Documentation

6.4.2.4 - IEnumerable

Any data type representing a collection of items that can iterated or looped over. The items contained in the collection can be any data type. List<TItem> is the most common example.

IEnumerable

(System.Collections.IEnumerable)

Summary

Any data type representing a collection of items that can iterated or looped over.

The items contained in the collection can be any data type.

List<TItem> is the most common example; for more see Most Common IEnumerable Data Types.

Category: Collections
Name: IEnumerable
Full Name: System.Collections.IEnumerable
Alias: N/A
Description: Any data type representing a collection of items that can iterated or looped over. The items contained in the collection can be any data type.
Size: Varies
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Remarks

Most Common IEnumerable Data Types

Any of the following data types can be used where an IEnumerable is required:

Create an IEnumerable

For some of the ways that an IEnumerable can be created, please see each of the IEnumerable data types:

Convert IEnumerable to Text

For some of the ways that an IEnumerable can be converted to text, please see each of the IEnumerable data types:

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is IEnumerable.
  • The Literal Editor is not available for Input properties where the data type is IEnumerable.
  • The Variable Editor is available for InputOutput and Output properties where the data type is IEnumerable.

Known Limitations

None

See Also

External Documentation

6.4.2.5 - IEnumerable<TItem>

Any data type representing a collection of items that can iterated or looped over. TItem indicates the data type of the items contained in the collection. List<TItem> is the most common example.

IEnumerable<TItem>

(System.Collections.Generic.IEnumerable<TItem>)

Summary

Any data type representing a collection of items that can iterated or looped over.

TItem indicates the data type of the items contained in the collection.

List<TItem> is the most common example; for more see Most Common IEnumerable<TItem> Data Types.

Category: Collections
Name: IEnumerable<TItem>
Full Name: System.Collections.Generic.IEnumerable<TItem>
Alias: N/A
Description: Any data type representing a collection of items that can iterated or looped over. TItem indicates the data type of the items contained in the collection.
Size: Varies
Default Value: null
Can be used as: IEnumerable, Object, dynamic
IEnumerable<TItemBaseType> (e.g. where IEnumerable<TItem> is IEnumerable<Int32> and IEnumerable<TItemBaseType> is IEnumerable<Object> as Object is a base type of Int32; this is called covariance)
Can be cast to: N/A

Remarks

Most Common IEnumerable<TItem> Data Types

Any of the following data types can be used where an IEnumerable<TItem> is required:

Create an IEnumerable<TItem>

For some of the ways that an IEnumerable<TItem> can be created, please see each of the IEnumerable<TItem> data types:

Convert IEnumerable<TItem> to Text

For some of the ways that an IEnumerable<TItem> can be converted to text, please see each of the IEnumerable<TItem> data types:

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is IEnumerable<TItem>.
  • The Literal Editor is not available for Input properties where the data type is IEnumerable<TItem>.
  • The Variable Editor is available for InputOutput and Output properties where the data type is IEnumerable<TItem>.

Known Limitations

None

See Also

External Documentation

6.4.2.6 - IList<TItem>

Any data type representing a list of items that can iterated or looped over. TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index. List<TItem> is the most common example.

IList<TItem>

(System.Collections.Generic.IList<TItem>)

Summary

Any data type representing a list of items that can iterated or looped over.

TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index.

List<TItem> is the most common example.

Category: Collections
Name: IList<TItem>
Full Name: System.Collections.Generic.IList<TItem>
Alias: N/A
Description: Any data type representing a list of items that can iterated or looped over. TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index.
Size: Varies
Default Value: null
Can be used as: IEnumerable<TItem>, IEnumerable, Object, dynamic
IEnumerable<TItemBaseType> (e.g. where IList<TItem> is IList<Int32> and IEnumerable<TItemBaseType> is IEnumerable<Object> as Object is a base type of Int32; this is called covariance)
Can be cast to: N/A

Remarks

Most Common IList<TItem> Data Types

Any of the following data types can be used where an IList<TItem> is required:

Create an IList<TItem>

For some of the ways that an IList<TItem> can be created, please see each of the IList<TItem> data types:

Convert IList<TItem> to Text

For some of the ways that an IList<TItem> can be converted to text, please see each of the IList<TItem> data types:

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is IList<TItem>.
  • The Literal Editor is not available for Input properties where the data type is IList<TItem>.
  • The Variable Editor is available for InputOutput and Output properties where the data type is IList<TItem>.

Known Limitations

None

See Also

External Documentation

6.4.2.7 - List<TItem>

Used to represent a list of items that can iterated or looped over. TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index.

List<TItem>

(System.Collections.Generic.List<TItem>)

Summary

The List<TItem> data type is used to represent a list of items that can iterated or looped over.

TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index.

Category: Collections
Name: List<TItem>
Full Name: System.Collections.Generic.List<TItem>
Alias: N/A
Description: A list of items that can iterated or looped over. TItem indicates the data type of the items contained in the list. Each TItem can be individually accessed by an index.
Size: Varies
Default Value: null
Can be used as: IList<TItem>, IEnumerable<TItem>, IEnumerable, Object, dynamic
IEnumerable<TItemBaseType> (e.g. where List<TItem> is List<Int32> and IEnumerable<TItemBaseType> is IEnumerable<Object> as Object is a base type of Int32; this is called covariance)
Can be cast to: N/A

Remarks

Create a List<TItem>

The following table shows some of the ways that a List<TItem> can be created.

Method Example Result Editor Support Notes
Declare a List<TItem> literal [] [] Expression List<dynamic> containing zero items
["Some Text"] ["Some Text"] Expression List<String> containing one String item
[true, false] [true, false] Expression List<Boolean> containing two Boolean items
[1, 2, 3] [1, 2, 3] Expression List<Int32> containing three Int32 items
["Some Text", true, 1] ["Some Text", true, 1] Expression List<dynamic> containing a String item, a Boolean item and an Int32 item
Use a List<TItem> expression new List<dynamic>() [] Expression List<dynamic> containing zero items
new List<String>() { "Some Text" } ["Some Text"] Expression List<String> containing one String item
new List<Boolean>() { true, false } [true, false] Expression List<Boolean> containing two Boolean items
new List<Int32>() { 1, 2, 3 } [1, 2, 3] Expression List<Int32> containing three Int32 items
new List<dynamic>() { "Some Text", true, 1 } ["Some Text", true, 1] Expression List<dynamic> containing a String item, a Boolean item and an Int32 item

Convert List<TItem> to Text

The following table shows some of the ways that a List<TItem> can be converted to text.

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a List<dynamic> value of ["Some Text", true, 1] "[\r\n \"Some Text\",\r\n true,\r\n 1\r\n]" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is List<TItem>.
  • The Literal Editor is not available for Input properties where the data type is List<TItem>.
  • The Variable Editor is available for InputOutput and Output properties where the data type is List<TItem>.

Known Limitations

None

See Also

External Documentation

6.4.2.8 - Structure

Used to represent a collection of key/item pairs, where the data type of the keys used to access the items contained in the collection is String and the items contained in the collection can be any data type. Each item can be individually accessed by its String key.

Structure

(Cortex.DataTypes.Dictionaries.Structure)

Summary

The Structure data type is used to represent a collection of key/item pairs.

The data type of the keys used to access the items contained in the collection is String and the items contained in the collection can be any data type. Each item can be individually accessed by its String key.

Category: Collections
Name: Structure
Full Name: Cortex.DataTypes.Dictionaries.Structure
Alias: N/A
Description: Used to represent a collection of key/item pairs, where the data type of the keys used to access the items contained in the collection is String and the items contained in the collection can be any data type. Each item can be individually accessed by its String key.
Size: Varies
Default Value: null
Can be used as: IDictionary<TKey, TItem>, IEnumerable, Object, dynamic
IEnumerable<KeyValuePair<TKey, TItem>> (e.g. where Structure is IDictionary<String, Object> and IEnumerable<KeyValuePair<TKey, TItem>> is IEnumerable<KeyValuePair<String, Object>>)
Can be cast to: N/A

Remarks

Create a Structure

The following table shows some of the ways that a Structure can be created.

Method Example Result Editor Support Notes
Declare a Structure literal {} {} Expression Structure containing zero items
{ "StringKey1": "StringValue" } { "StringKey1": "StringValue" } Expression Structure containing one String item with a String key
{ "StringKey1": true, "StringKey2": false } { "StringKey1": true, "StringKey2": false } Expression Structure containing two Boolean items with String keys
{ "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 } { "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 } Expression Structure containing three Int32 item with String keys
{ "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } { "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } Expression Structure containing a String item, a Boolean item and an Int32 item with String keys
Use a Structure expression new Structure() {} Expression Structure containing zero items
new Structure() { { "StringKey1", "StringValue" } } { "StringKey1": "StringValue" } Expression Structure containing one String item with a String key
new Structure() { { "StringKey1", true }, { "StringKey2", false } } { "StringKey1": true, "StringKey2": false } Expression Structure containing two Boolean items with String keys
new Structure() { { "StringKey1", 1 }, { "StringKey2", 2 }, { "StringKey3", 3 } } { "StringKey1": 1, "StringKey2": 2, "StringKey3": 3 } Expression Structure containing three Int32 item with String keys
new Structure() { { "StringKey1", "StringValue" }, { "StringKey2", true }, { "StringKey3", 1 } } { "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } Expression Structure containing a String item, a Boolean item and an Int32 item with String keys

Convert Structure to Text

The following table shows some of the ways that a Structure can be converted to text.

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a Structure value of { "StringKey1": "StringValue", "StringKey2": true, "StringKey3": 1 } "{\r\n \"StringKey1\": \"StringValue\",\r\n \"StringKey2\": true,\r\n \"StringKey3\": 1\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Structure.
  • The Literal Editor is not available for Input properties where the data type is Structure.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Structure.

Known Limitations

None

See Also

External Documentation

N/A

6.4.3 - Conditional Logic

Data types used for working with conditional logic.

6.4.3.1 - Boolean

Used to represent a logical value of true or false.

Boolean

(System.Boolean)

Summary

The Boolean data type is used to represent a logical value of true or false.

Category: Conditional Logic
Name: Boolean
Full Name: System.Boolean
Alias: bool
Description: A logical value of true or false.
Size: 1 bit
Default Value: false
Can be used as: Nullable<Boolean>, Object, dynamic
Can be cast to: N/A

Remarks

Create a Boolean

The following table shows some of the ways that a Boolean can be created.

Method Example Result Editor Support Notes
Declare a Boolean literal true true Literal, Expression True
false false Literal, Expression False
Use a Boolean expression 1 == 1 true Expression Uses equals operator
1 != 1 false Expression Uses not equals operator
1 > 0 true Expression Uses greater than operator
1 < 0 false Expression Uses less than operator
1 >= 0 true Expression Uses greater than or equals operator
1 <= 0 false Expression Uses less than or equals operator
true && false false Expression Uses logical AND operator
true || false true Expression Uses logical OR operator
!(true || false) false Expression Uses logical NOT operator
Boolean.Parse("true") true Expression Attempts to parse text and convert it to a Boolean value. See Boolean.Parse
Convert.ToBoolean("true") true Expression Attempts to convert text to a Boolean value. See Convert.ToBoolean

Convert Boolean to Text

The following table shows some of the ways that a Boolean can be converted to text.

Method Example Result Editor Support Notes
Use ToString true.ToString() "True" Expression See Boolean.ToString
($)BooleanVariable.ToString() where ($)BooleanVariable has a value of true "True" Expression See Boolean.ToString
Use Convert.ToString Convert.ToString(true) "True" Expression See Convert.ToString
Convert.ToString(($)BooleanVariable) where ($)BooleanVariable has a value of true "True" Expression See Convert.ToString
Use Convert Object To Text block where Object property has a value of true "True" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of true "true" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Boolean.
  • The Literal Editor is available for Input properties where the data type is Boolean.
    • Expression syntax is not supported within the Literal Editor for the Boolean data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Boolean.

Known Limitations

None

See Also

None

None

External Documentation

6.4.4 - Credentials

Data types used for working with credentials.

6.4.4.1 - UserCredentials

Used to represent details required to authenticate with a domain or server.

UserCredentials

(Cortex.DataTypes.Credentials.UserCredentials)

Summary

The UserCredentials data type is used to represent details required to authenticate with a domain or server.

Category: Credentials
Name: UserCredentials
Full Name: Cortex.DataTypes.Credentials.UserCredentials
Alias: N/A
Description: Details required to authenticate with a domain or server.
Default Value: null
Can be used as: EmailUserCredentials, EmailCredentials, IEmailCredentials, HttpUserCredentials, HttpCredentials, IHttpCredentials, SshUserCredentials, SshCredentials, ISshCredentials, UserCredentials, NetworkCredential, Object, dynamic
Can be cast to: N/A

Properties

Domain

The Domain is used to define the domain or server to authenticate with. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

Whether or not the Domain is required is dependent on the block being used:

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value ""

Username

The Username is used to define the user to authenticate as. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value ""

Password

The Password is used to define the password of the user to authenticate as. This property is an EncryptedText and so it must be encrypted; for more information on how to encrypt the password, see EncryptedText.

Data Type EncryptedText
Is Advanced false
Default Editor Expression
Default Value EncryptedText with value ""

Exceptions

The exceptions thrown by the data type can be found below:

Name Description
UnencryptedTextException Thrown when the Password is not encrypted.

Remarks

Create a UserCredentials

The following table shows some of the ways that UserCredentials can be created.

Method Example Result Editor Support Notes
Use a UserCredentials constructor new UserCredentials(domain: "domain", username: "username", password: "encryptedPassword") {"Domain": "domain", "Username": "username", "Password": "encryptedPassword"} Expression Domain specified
new UserCredentials(username: "username", password: "encryptedPassword") {"Domain": null, "Username": "username", "Password": "encryptedPassword"} Expression Domain not specified

A UserCredentials can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
Domain EncryptableText "domain" Domain defines the domain or server to authenticate with.
Username EncryptableText "username" Username defines the user to authenticate as.
Password EncryptedText "encryptedPassword" Password defines the password of the user to authenticate as.

Convert UserCredentials to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"Domain": "domain", "Username": "username", "Password": "encryptedPassword"} "{\r\n \"Domain\": \"domain\",\r\n \"Username\": \"username\",\r\n \"Password\": \"encryptedPassword\"\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is UserCredentials.
  • The Literal Editor is available for Input properties where the data type is UserCredentials.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is UserCredentials.

Known Limitations

None

See Also

External Documentation

6.4.5 - Data

Data types used for working with data sources such as SQL Server.

6.4.5.1 - Command

Defines a single statement that can be run against a data source.

Command

(Cortex.DataTypes.Data.Command)

Summary

A Command data type is used to define a single statement that can be run against a data source. The statement can be parameterised, which is recommended to prevent SQL Injection.

Category: Data
Name: Command
Full Name: Cortex.DataTypes.Data.Command
Alias: N/A
Description: Defines a single statement that can be run against a data source.
Default Value: null
Can be used as: DataCommand, Object, dynamic
Can be cast to: N/A

Properties

Command Text

The Command Text is used to define a single statement that will be run against the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

Parameters

Parameters are used to pass information to the statement that will be run against the data source.

It is recommended to always use Parameterised Commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

For more information see Parameterised Commands.

Data Type dynamic
Is Advanced true
Default Editor Expression
Default Value dynamic with no value

Remarks

Create a Command

The following table shows some of the ways that a Command can be created.

Method Example Result Editor Support Notes
Use a Command constructor new Command("SELECT * FROM Table", null) {CommandText: "SELECT * FROM Table", Parameters: null} Expression
new Command("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3}) {"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}} Expression It is recommended to always use Parameterised Commands as they prevent SQL Injection

A Command can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
CommandText EncryptableText $@"SELECT * FROM Table WHERE Id < @SelectParameter" The command that will be executed or queried against the data source.
Parameters dynamic new {SelectParameter = 3} The parameters that are used within a Parameterised Command.

Convert Command to Text

Method Example Result Editor Support Notes
Use ToString ($)Command.ToString() "Cortex.DataTypes.Data.Command" Expression ToString will return the Full Name of the Command Data Type
Use Convert Object To Text block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "Cortex.DataTypes.Data.Command" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}" N/A See Convert Object To Json

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "SELECT * FROM Table WHERE Name = @Parameter"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

For more information see Parameterised Commands.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Command.
  • The Literal Editor is not available for Input properties where the data type is Command.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is Command.

Known limitations

ToString Method always returns the Full Name

Currently, if the ToString() method is used on a Command, then its Full Name will be returned; instead of a representation of the data within the Command.

In future this limitation may be removed.

See Also

External Documentation

6.4.5.2 - Commands

Holds the information for parsing a command, running multiple query and non query commands against a data source.

Commands

(Cortex.DataTypes.Data.Commands)

Summary

A Commands data type is used to define single or multiple statements that can be run against a data source. Statements can be parameterised, which is recommended to prevent SQL Injection.

Category: Data
Name: Commands
Full Name: Cortex.DataTypes.Data.Commands
Alias: N/A
Description: Defines single or multiple statements that can be run against a data source.
Default Value: null
Can be used as: DataCommand, Object, dynamic
Can be cast to: N/A

Properties

Command Text

The Command Text is used to define single or multiple statements that will be run against the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

Parameters

Parameters are used to pass information to the single or multiple statements that will be run against the data source.

It is recommended to always use Parameterised Commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

For more information see Parameterised Commands.

Data Type dynamic
Is Advanced true
Default Editor Expression
Default Value dynamic with no value

Remarks

Create a Commands

The following table shows some of the ways that a Commands can be created.

Method Example Result Editor Support Notes
Use a Commands constructor new Commands("SELECT * FROM Table", null) {CommandText: "SELECT * FROM Table", Parameters: null} Expression
new Commands("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3}) {"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}} Expression It is recommended to always use Parameterised Commands as they prevent SQL Injection

A Commands can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
CommandText EncryptableText $@"SELECT * FROM Table WHERE Id < @SelectParameter" The command that will be executed or queried against the data source.
Parameters dynamic new {SelectParameter = 3} The parameters that are used within a Parameterised Command.

Convert Commands to Text

Method Example Result Editor Support Notes
Use ToString ($)Commands.ToString() "Cortex.DataTypes.Data.Commands" Expression ToString will return the Full Name of the Commands Data Type
Use Convert Object To Text block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "Cortex.DataTypes.Data.Commands" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}" N/A See Convert Object To Json

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "SELECT * FROM Table WHERE Name = @Parameter"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

For more information see Parameterised Commands.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Commands.
  • The Literal Editor is available for Input properties where the data type is Commands.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is Commands.

Known limitations

ToString Method always returns the Full Name

Currently, if the ToString() method is used on a Commands, then its Full Name will be returned; instead of a representation of the data within the Commands.

In future this limitation may be removed.

See Also

External Documentation

6.4.5.3 - ConnectionDetails

Any data type representing configuration for establishing and maintaining a connection to a data source.

ConnectionDetails

(Cortex.DataTypes.Data.ConnectionDetails)

Summary

Any data type representing configuration for establishing and maintaining a connection to a data source.

Category: Data
Name: ConnectionDetails
Full Name: Cortex.DataTypes.Data.ConnectionDetails
Alias: N/A
Description: Any data type representing configuration for establishing and maintaining a connection to a data source.
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Remarks

Most Common ConnectionDetails Data Types

Any of the following data types can be used where a ConnectionDetails is required:

Create a ConnectionDetails

For some of the ways that a ConnectionDetails can be created, please see each of the ConnectionDetails data types:

Convert ConnectionDetails to Text

For some of the ways that a ConnectionDetails can be converted to text, please see each of the ConnectionDetails data types:

Known limitations

None

See Also

External Documentation

None

6.4.5.4 - DataCommand

Any data type representing configuration for data source commands.

DataCommand

(Cortex.DataTypes.Data.DataCommand)

Summary

Any data type representing configuration for data source commands.

Category: Data
Name: DataCommand
Full Name: Cortex.DataTypes.Data.DataCommand
Alias: N/A
Description: Any data type representing configuration for data source commands.
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Properties

Command Text

The Command Text is used to create the command that will be run against the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

Parameters

Parameters are used to pass information to the command that will be run against the data source.

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

For more information see Parameterised Commands

Data Type dynamic
Is Advanced true
Default Editor Expression
Default Value dynamic with no value

Remarks

Most Common DataCommand Data Types

Any of the following data types can be used where a DataCommand is required:

Create a DataCommand

For some of the ways that a DataCommand can be created, please see each of the DataCommand data types:

Convert DataCommand to Text

For some of the ways that a DataCommand can be converted to text, please see each of the DataCommand data types:

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "SELECT * FROM Table WHERE Name = @Parameter"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

For more information see Parameterised Commands.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is DataCommand.
  • The Literal Editor is available for Input properties where the data type is DataCommand.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is DataCommand.

Known limitations

None

See Also

External Documentation

6.4.5.5 - NonQueryCommand

Holds the information for running a Non Query command against a data source.

NonQueryCommand

(Cortex.DataTypes.Data.NonQueryCommand)

Summary

A NonQueryCommand data type is used to define single or multiple Non Query Statements that can be run against a data source. Statements can be parameterised, which is recommended to prevent SQL Injection.

Category: Data
Name: NonQueryCommand
Full Name: Cortex.DataTypes.Data.NonQueryCommand
Alias: N/A
Description: Defines single or multiple Non Query Statements that can be run against a data source.
Default Value: null
Can be used as: DataCommand, Object, dynamic
Can be cast to: N/A

Properties

Command Text

The Command Text is used to define single or multiple Non Query Statements that will be run against the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

Parameters

Parameters are used to pass information to the Non Query Statements that will be run against the data source.

It is recommended to always use Parameterised Commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

For more information see Parameterised Commands.

Data Type dynamic
Is Advanced true
Default Editor Expression
Default Value dynamic with no value

Remarks

Create a NonQueryCommand

The following table shows some of the ways that a NonQueryCommand can be created.

Method Example Result Editor Support Notes
Use a NonQueryCommand constructor new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", null) {CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null} Expression
new NonQueryCommand("INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", new { InsertParameter1 = "Value1", InsertParameter2 = "Value2" }) {"CommandText": "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)", "Parameters": { "InsertParameter1": \"Value1\", "InsertParameter2": \"Value2\" } } Expression It is recommended to always use Parameterised Commands as they prevent SQL Injection

A NonQueryCommand can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
CommandText EncryptableText $@"INSERT INTO Table (FirstColumn, SecondColumn) VALUES (@InsertParameter1, @InsertParameter2)" The command that will be executed against the data source.
Parameters dynamic new { InsertParameter1 = "Value1", InsertParameter2 = "Value2" }) The parameters that are used within a Parameterised Command.

Convert NonQueryCommand to Text

Method Example Result Editor Support Notes
Use ToString ($)NonQueryCommand.ToString() "Cortex.DataTypes.Data.NonQueryCommand" Expression ToString will return the Full Name of the NonQueryCommand Data Type
Use Convert Object To Text block where Object property has a value of {CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null} "Cortex.DataTypes.Data.NonQueryCommand" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of {CommandText: "INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\"Value1\", \"Value2\")", Parameters: null} "{\r\n \"CommandText\": \"INSERT INTO Table (FirstColumn, SecondColumn) VALUES (\\\"Value1\\\", \\\"Value2\\\")\",\r\n \"Parameters\": null\r\n}" N/A See Convert Object To Json

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "INSERT INTO Table (FirstColumn) VALUES (@Parameter)"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

For more information see Parameterised Commands.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is NonQueryCommand.
  • The Literal Editor is available for Input properties where the data type is NonQueryCommand.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is

Known limitations

ToString Method always returns the Full Name

Currently, if the ToString() method is used on a NonQueryCommand, then its Full Name will be returned; instead of a representation of the data within the NonQueryCommand.

In future this limitation may be removed.

See Also

External Documentation

6.4.5.6 - OdbcConnectionDetails

The data type representing configuration for establishing and maintaining a connection to an ODBC data source.

OdbcConnectionDetails

(Cortex.DataTypes.Data.OdbcConnectionDetails)

Summary

The OdbcConnectionDetails data type is used to establish and maintain a connection to an ODBC data source.

Category: Data
Name: OdbcConnectionDetails
Full Name: Cortex.DataTypes.Data.OdbcConnectionDetails
Alias: N/A
Description: The data type representing configuration for establishing and maintaining a connection to an ODBC data source.
Default Value: null
Can be used as: ConnectionDetails, Object, dynamic
Can be cast to: N/A

Properties

Connection String

The Connection String that is used to connect to an ODBC data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@"Dsn=DSN Name;Driver=Driver Name;"

Remarks

Create an OdbcConnectionDetails

The following table shows some of the ways that a OdbcConnectionDetails can be created.

Method Example Result Editor Support Notes
Use an OdbcConnectionDetails constructor new OdbcConnectionDetails("DSN=LocalHost;Driver={ODBC Driver Version}") {"ConnectionString": "DSN=LocalHost;Driver={ODBC Driver Version}"} Expression

A OdbcConnectionDetails can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
Connection String EncryptableText $@"DSN=LocalHost;Driver={ODBC Driver Version}" The Connection String that is used to connect to an ODBC data source.

Connection Strings

A Connection String must be provided in order to connect to an ODBC data source. The Connection String can be formatted differently depending on the ODBC driver. See ConnectionStrings.com for a list of ODBC connection strings under each specific data source.

Please see Working with Data Sources for a list of other supported data sources (e.g. SQL Server) and how to construct valid connection strings for them.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is OdbcConnectionDetails.
  • The Literal Editor is not available for Input properties where the data type is OdbcConnectionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is OdbcConnectionDetails.

Known limitations

  • Currently string values cannot be used as a parameter when connected to an Microsoft Access data source.

See Also

External Documentation

6.4.5.7 - QueryCommand

Holds the information for running a Query command against a data source.

QueryCommand

(Cortex.DataTypes.Data.QueryCommand)

Summary

A QueryCommand data type is used to define single or multiple Query Statements that can be run against a data source. Statements can be parameterised, which is recommended to prevent SQL Injection.

Category: Data
Name: QueryCommand
Full Name: Cortex.DataTypes.Data.QueryCommand
Alias: N/A
Description: Defines single or multiple Query Statements that can be run against a data source.
Default Value: null
Can be used as: DataCommand, Object, dynamic
Can be cast to: N/A

Properties

Command Text

The Command Text is used to define single or multiple Query Statements that will be run against the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

Parameters

Parameters are used to pass information to the Query Statements that will be run against the data source.

It is recommended to always use Parameterised Commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

For more information see Parameterised Commands.

Data Type dynamic
Is Advanced true
Default Editor Expression
Default Value dynamic with no value

Remarks

Create a QueryCommand

The following table shows some of the ways that a QueryCommand can be created.

Method Example Result Editor Support Notes
Use a QueryCommand constructor new QueryCommand("SELECT * FROM Table", null) {CommandText: "SELECT * FROM Table", Parameters: null} Expression
new QueryCommand("SELECT * FROM Table WHERE Id < @SelectParameter", new {SelectParameter = 3}) {"CommandText": "SELECT * FROM Table WHERE Id < @SelectParameter", "Parameters": {"SelectParameter": 3}} Expression It is recommended to always use Parameterised Commands as they prevent SQL Injection

A QueryCommand can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
CommandText EncryptableText $@"SELECT * FROM Table WHERE Id < @SelectParameter" The command that will be queried against the data source.
Parameters dynamic new { SelectParameter = 3 }) The parameters that are used within a Parameterised Command.

Convert QueryCommand to Text

Method Example Result Editor Support Notes
Use ToString ($)QueryCommand.ToString() "Cortex.DataTypes.Data.QueryCommand" Expression ToString will return the Full Name of the QueryCommand Data Type
Use Convert Object To Text block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "Cortex.DataTypes.Data.QueryCommand" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of {CommandText: "SELECT * FROM Table", Parameters: null} "{\r\n \"CommandText\": \"SELECT * FROM Table\",\r\n \"Parameters\": null\r\n}" N/A See Convert Object To Json

Parameterised Commands

It is recommended to always use parameterised commands as they prevent SQL Injection attacks by ensuring the parameters are sanitised before the command is executed.

The @ symbol denotes a parameter within the CommandText (e.g. "SELECT * FROM Table WHERE Name = @Parameter"). An example of using parameters can be found in Executing Multiple Commands (Safe), whereas, an example of inserting variables into a statement without parameters can be found in Executing Multiple Commands (Unsafe)

For more information see Parameterised Commands.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is QueryCommand.
  • The Literal Editor is available for Input properties where the data type is QueryCommand.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is QueryCommand.

Known limitations

ToString Method always returns the Full Name

Currently, if the ToString() method is used on a QueryCommand, then its Full Name will be returned; instead of a representation of the data within the QueryCommand.

In future this limitation may be removed.

See Also

External Documentation

6.4.5.8 - SqlServerConnectionDetails

The data type representing configuration for establishing and maintaining a connection to an SQL Server data source.

SqlServerConnectionDetails

(Cortex.DataTypes.Data.SqlServerConnectionDetails)

Summary

The SqlServerConnectionDetails data type is used to establish and maintain a connection to a SQL Server data source.

Category: Data
Name: SqlServerConnectionDetails
Full Name: Cortex.DataTypes.Data.SqlServerConnectionDetails
Alias: N/A
Description: The data type representing configuration for establishing and maintaining a connection to an SQL Server data source.
Default Value: null
Can be used as: ConnectionDetails, Object, dynamic
Can be cast to: N/A

Properties

Connection String

The Connection String that is used to connect to the data source.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@"Server=localhost;Database=YourDatabase;Trusted_Connection=true;"

Remarks

Create a SqlServerConnectionDetails

The following table shows some of the ways that a SqlServerConnectionDetails can be created.

Method Example Result Editor Support Notes
Use a SqlServerConnectionDetails constructor new SqlServerConnectionDetails("Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;") {"ConnectionString": "Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;"} Expression

A SqlServerConnectionDetails can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
Connection String EncryptableText $@"Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;" The Connection String that is used to connect to the data source.

Connection Strings

A Connection String must be provided in order to connect to a SQL Server data source. The Connection String can be formatted differently depending either on the version of SQL Server or the way the connection will be created and maintained (e.g. Trusted connection vs explicit user). See ConnectionStrings.com for a list of connection strings for SQL Server.

Please see Working with Data Sources for a list of other supported data sources (e.g. ODBC) and how to construct valid connection strings for them.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is SqlServerConnectionDetails.
  • The Literal Editor is not available for Input properties where the data type is SqlServerConnectionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is SqlServerConnectionDetails.

Known limitations

None

See Also

External Documentation

6.4.6 - Date & Time

Data types used for working with dates and time.

6.4.6.1 - DateTime

Used to represent a date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar. It can be used wherever a DateTimeOffset is expected, and will be implicitly cast.

DateTime

(System.DateTime)

Summary

The DateTime data type is used to represent a date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar. It can be used wherever a DateTimeOffset is expected, and will be implicitly cast.

Category: Date & Time
Name: DateTime
Full Name: System.DateTime
Alias: N/A
Description: A date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar. It can be used wherever a DateTimeOffset is expected, and will be implicitly cast.
Size: Varies, typically 8 bytes
Default Value: 0001-01-01T00:00:00 (i.e. DateTime.MinValue)
Can be used as: DateTimeOffset, Object, dynamic
Can be cast to: N/A

Remarks

Create a DateTime

The following table shows some of the ways that a DateTime can be created.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Method Example Result Editor Support Notes
Use DateTime.Now DateTime.Now 2022-07-01T14:00:00.0000000+01:00 Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as local time. See DateTime.Now
Use DateTime.UtcNow DateTime.UtcNow 2022-07-01T13:00:00.0000000Z Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC). See DateTime.UtcNow
Use DateTime.Parse DateTime.Parse("1/7/2022 2:00:00 PM") 2022-07-01T14:00:00 Expression Parses a date string and converts it to a DateTime using the current culture of the system. In this example it parses "1/7/2022 2:00:00 PM" using en-GB culture and converts it to 2022-07-01T14:00:00. See DateTime.Parse
Use a DateTime constructor new DateTime(2022, 7, 1, 14, 0, 0, 0) 2022-07-01T14:00:00 Expression 2PM 1st July 2022 with 1 hour UTC offset, honouring British Summer Time (BST). See DateTime Constructors.
Use DateTimeOffset.DateTime DateTimeOffset.UtcNow.DateTime 2022-07-01T13:00:00.0000000 Expression Converts DateTimeOffset.UtcNow to a DateTime using the date and time components, but not the offset. See DateTimeOffset.DateTime
Use DateTimeOffset.LocalDateTime DateTimeOffset.UtcNow.LocalDateTime 2022-07-01T14:00:00.0000000+01:00 Expression Converts DateTimeOffset.UtcNow to a DateTime relative to the local time. See DateTimeOffset.LocalDateTime
Use DateTimeOffset.UtcDateTime DateTimeOffset.UtcNow.UtcDateTime 2022-07-01T13:00:00.0000000Z Expression Converts DateTimeOffset.UtcNow to a DateTime relative to Coordinated Universal Time (UTC). See DateTimeOffset.UtcDateTime

Please see Initializing a DateTime object for further information.

Convert DateTime to Text

The following table shows some of the ways that a DateTime can be converted to text.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Method Example Result Editor Support Notes
Use ToString DateTime.UtcNow.ToString() "1/7/2022 1:00:00 PM" Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the short date pattern for the current culture and the long time pattern for the current culture with each element separated from the previous element by a space. See DateTime.ToString
Use Convert.ToString Convert.ToString(DateTime.UtcNow) "1/7/2022 1:00:00 PM" Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the short date pattern for the current culture and the long time pattern for the current culture, with each element separated from the previous element by a space. See Convert.ToString
Use Convert DateTime To Text block where Date Time property has a value of DateTime.UtcNow "2022-07-01T13:00:00.0000000+00:00" Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use ISO 8601 Standard format for DateTimeOffset (i.e. yyyy-MM-ddTHH:mm:ss.fffffffzzz) as the Convert DateTime To Text block will impicitly convert a DateTime to a DateTimeOffset. See Convert DateTime To Text
Use Convert Object To Text block where Object property has a value of DateTime.UtcNow "1/7/2022 1:00:00 PM" Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use the short date pattern for the current culture and the long time pattern for the current culture, with each element separated from the previous element by a space. See Convert Object To Text
Use Convert Object To Json block where Object property has a value of DateTime.UtcNow "\"2022-07-01T13:00:00.0000000Z\"" Expression The result shown is an example result. The actual result will show the current date and time on the current computer expressed as the Coordinated Universal Time (UTC) converted to text. Both the example and actual result will use ISO 8601 Standard format for DateTime (i.e. yyyy-MM-ddTHH:mm:ss.fffffffK). See Convert Object To Json

Please see Date and Time Formatting for further information on formatting DateTime values, including how Operating System Settings can affect the current culture.

Convert DateTime to a DateTimeOffset

DateTime values will be implicitly cast to DateTimeOffset values if used where a DateTimeOffset is expected.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is DateTime.
  • The Literal Editor is available for Input properties where the data type is DateTime.
    • Expression syntax is not supported within the Literal Editor for the DateTime data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is DateTime.

Known Limitations

None

See Also

External Documentation

6.4.6.2 - DateTimeComponentType

Used to represent a component of a DateTimeOffset (e.g. Year, Month, Day).

DateTimeComponentType

(Cortex.DataTypes.DateAndTime.DateTimeComponentType)

Summary

Values

LocalDateTime

UtcDateTime

Date

Time

Year

Month

Day

Hour

Minute

Second

Millisecond

Offset

DayOfYear

DayOfWeek

Remarks

Create a DateTimeComponentType

Convert DateTimeComponentType to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.6.3 - DateTimeOffset

Used to represent a date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar, along with a UTC time offset.

DateTimeOffset

(System.DateTimeOffset)

Summary

The DateTimeOffset data type is used to represent a date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar, along with a UTC time offset.

Category: Date & Time
Name: DateTimeOffset
Full Name: System.DateTimeOffset
Alias: N/A
Description: A date and time between 00:00:00.0000000 UTC, January 1, 0001 and 23:59:59.9999999 UTC, December 31, 9999, in the Gregorian calendar, along with a UTC time offset.
Size: Varies, typically 12 to 16 bytes
Default Value: 0001-01-01T00:00:00+00:00 (i.e. DateTimeOffset.MinValue)
Can be used as: Object, dynamic
Can be cast to: N/A

Remarks

Create a DateTimeOffset

The following table shows some of the ways that a DateTimeOffset can be created.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Method Example Result Editor Support Notes
Use DateTimeOffset.Now DateTimeOffset.Now 2022-07-01T14:00:00.0000000+01:00 Expression The result shown is an example result. The actual result will show the current date and time on the current computer, with the offset set to the local time’s offset from Coordinated Universal Time (UTC). See DateTimeOffset.Now.
Use DateTimeOffset.UtcNow DateTimeOffset.UtcNow 2022-07-01T13:00:00.0000000+00:00 Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero. See DateTimeOffset.UtcNow.
Implicit Casting of DateTime DateTime.UtcNow 2022-07-01T13:00:00.0000000+00:00 Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero.
Use DateTimeOffset.Parse DateTimeOffset.Parse("1/7/2022 2:00:00 PM +1:00") 2022-07-01T14:00:00+01:00 Expression Parses a date string and converts it to a DateTimeOffset using the current culture of the system. In this example it parses "1/7/2022 2:00:00 PM +1:00" using en-GB culture and converts it to 2022-07-01T14:00:00+01:00. See DateTimeOffset.Parse
Use a DateTimeOffset constructor new DateTimeOffset(2022, 7, 1, 14, 0, 0, 0, new TimeSpan(1, 0, 0)) 2022-07-01T14:00:00+01:00 Expression 2PM 1st July 2022 with 1 hour UTC offset, honouring British Summer Time (BST). See DateTimeOffset Constructors.
Use Convert Text To DateTime block where Text property has a value of "1/7/2022 2:00:00 PM +1:00" 2022-07-01T14:00:00+01:00 Expression Parses a date string and converts it to a DateTimeOffset. See Convert Text To DateTime

Please see Instantiating a DateTimeOffset object for further information.

A DateTimeOffset can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Notes
Year Int32 The year expressed as an Int32 value between 1 and 9999.
Month Int32 The month expressed as an Int32 value between 1 and 12.
Day Int32 The day expressed as an Int32 value between 1 and the number of days in Month.
Hour Int32 The hour expressed as an Int32 value between 0 and 23.
Minute Int32 The minute expressed as an Int32 value between 0 and 59.
Second Int32 The second expressed as an Int32 value between 0 and 59.
Millisecond Int32 The millisecond expressed as an Int32 value between 0 and 999.
Offset TimeSpan The UTC Offset expressed as a TimeSpan value between -14 hours and 14 hours. This is calculated as the sum of Offset.Days + Offset.Hours + Offset.Minutes + Offset.Seconds + Offset.Milliseconds. If the value is outside -14 hours and 14 hours an InvalidPropertyValueException will be thrown.

Convert DateTimeOffset to Text

The following table shows some of the ways that a DateTimeOffset can be converted to text.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Method Example Result Editor Support Notes
Use ToString DateTimeOffset.UtcNow.ToString() "1/7/2022 1:00:00 PM +00:00" Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the short date pattern for the current culture, the long time pattern for the current culture, and the zzz custom format string, with each element separated from the previous element by a space. See DateTimeOffset.ToString
Use Convert.ToString Convert.ToString(DateTimeOffset.UtcNow) "1/7/2022 1:00:00 PM +00:00" Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the short date pattern for the current culture, the long time pattern for the current culture, and the zzz custom format string, with each element separated from the previous element by a space. See Convert.ToString
Use Convert DateTime To Text block where Date Time property has a value of DateTimeOffset.UtcNow "2022-07-01T13:00:00.0000000+00:00" Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use ISO 8601 Standard format for DateTimeOffset (i.e. yyyy-MM-ddTHH:mm:ss.fffffffzzz). See Convert DateTime To Text
Use Convert Object To Text block where Object property has a value of DateTimeOffset.UtcNow "1/7/2022 1:00:00 PM +00:00" Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use the short date pattern for the current culture, the long time pattern for the current culture, and the zzz custom format string, with each element separated from the previous element by a space. See Convert Object To Text
Use Convert Object To Json block where Object property has a value of DateTimeOffset.UtcNow "\"2022-07-01T13:00:00.0000000+00:00\"" Expression The result shown is an example result. The actual result will show the current Coordinated Universal Time (UTC) date and time and whose offset is Zero converted to text. Both the example and actual result will use ISO 8601 Standard format for DateTimeOffset (i.e. yyyy-MM-ddTHH:mm:ss.fffffffzzz). See Convert Object To Json

Please see Date and Time Formatting for further information on formatting DateTimeOffset values, including how Operating System Settings can affect the current culture.

Convert DateTimeOffset to a DateTime

The following table shows some of the ways that a DateTimeOffset can be converted to a DateTime.

All examples are for a system configured with British culture (i.e. en-GB), and use a local time of 2PM 1st of July 2022 with 1 hour UTC offset, honouring British Summer Time (BST).

Method Example Result Editor Support Notes
Use DateTimeOffset.DateTime DateTimeOffset.UtcNow.DateTime 2022-07-01T13:00:00.0000000 Expression Converts DateTimeOffset.UtcNow to a DateTime using the date and time components, but not the offset. See DateTimeOffset.DateTime
Use DateTimeOffset.LocalDateTime DateTimeOffset.UtcNow.LocalDateTime 2022-07-01T14:00:00.0000000+01:00 Expression Converts DateTimeOffset.UtcNow to a DateTime relative to the local time. See DateTimeOffset.LocalDateTime
Use DateTimeOffset.UtcDateTime DateTimeOffset.UtcNow.UtcDateTime 2022-07-01T13:00:00.0000000Z Expression Converts DateTimeOffset.UtcNow to a DateTime relative to Coordinated Universal Time (UTC). See DateTimeOffset.UtcDateTime

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is DateTimeOffset.
  • The Literal Editor is available for Input properties where the data type is DateTimeOffset.
    • Expression syntax is not supported within the Literal Editor for the DateTimeOffset data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is DateTimeOffset.

Known Limitations

None

See Also

External Documentation

6.4.6.4 - DayOfWeek

Used to represent a day of the week from Sunday (i.e. DayOfWeek.Sunday) through Saturday (i.e. DayOfWeek.Saturday).

DayOfWeek

(System.DayOfWeek)

Summary

The DayOfWeek data type is used to represent a day of the week from Sunday (i.e. DayOfWeek.Sunday) through Saturday (i.e. DayOfWeek.Saturday).

DayOfWeek is an enum data type, which means it has a defined set of values, where each value has an associated String name and Int32 value.

Category: Date & Time
Name: DayOfWeek
Full Name: System.DayOfWeek
Alias: N/A
Description: A day of the week from Sunday (i.e. DayOfWeek.Sunday) through Saturday (i.e. DayOfWeek.Saturday).
Size: 4 bytes
Values: DayOfWeek.Sunday where name is "Sunday" and value is 0
DayOfWeek.Monday where name is "Monday" and value is 1
DayOfWeek.Tuesday where name is "Tuesday" and value is 2
DayOfWeek.Wednesday where name is "Wednesday" and value is 3
DayOfWeek.Thursday where name is "Thursday" and value is 4
DayOfWeek.Friday where name is "Friday" and value is 5
DayOfWeek.Saturday where name is "Saturday" and value is 6
Default Value: DayOfWeek.Sunday
Can be used as: Object, dynamic
Can be cast to: Int16 (e.g. (Int16)DayOfWeek.Sunday or (System.Int16)DayOfWeek.Sunday or (short)DayOfWeek.Sunday)
Int32 (e.g. (Int32)DayOfWeek.Sunday or (System.Int32)DayOfWeek.Sunday or (int)DayOfWeek.Sunday)
Int64 (e.g. (Int64)DayOfWeek.Sunday or (System.Int64)DayOfWeek.Sunday or (long)DayOfWeek.Sunday)
Single (e.g. (Single)DayOfWeek.Sunday or (System.Single)DayOfWeek.Sunday or (float)DayOfWeek.Sunday)
Double (e.g. (Double)DayOfWeek.Sunday or (System.Double)DayOfWeek.Sunday or (double)DayOfWeek.Sunday)

Remarks

Create a DayOfWeek

The following table shows some of the ways that a DayOfWeek can be created.

Method Example Result Editor Support Notes
Declare a DayOfWeek literal Sunday DayOfWeek.Sunday Literal Indicates Sunday
Monday DayOfWeek.Monday Literal Indicates Monday
Tuesday DayOfWeek.Tuesday Literal Indicates Tuesday
Wednesday DayOfWeek.Wednesday Literal Indicates Wednesday
Thursday DayOfWeek.Thursday Literal Indicates Thursday
Friday DayOfWeek.Friday Literal Indicates Friday
Saturday DayOfWeek.Saturday Literal Indicates Saturday
Use a DayOfWeek expression DayOfWeek.Sunday DayOfWeek.Sunday Expression Indicates Sunday
DayOfWeek.Monday DayOfWeek.Monday Expression Indicates Monday
DayOfWeek.Tuesday DayOfWeek.Tuesday Expression Indicates Tuesday
DayOfWeek.Wednesday DayOfWeek.Wednesday Expression Indicates Wednesday
DayOfWeek.Thursday DayOfWeek.Thursday Expression Indicates Thursday
DayOfWeek.Friday DayOfWeek.Friday Expression Indicates Friday
DayOfWeek.Saturday DayOfWeek.Saturday Expression Indicates Saturday
Use Explicit Casting (DayOfWeek)0 DayOfWeek.Sunday Expression Casts 0 to DayOfWeek.Sunday
(DayOfWeek)1 DayOfWeek.Monday Expression Casts 1 to DayOfWeek.Monday
(DayOfWeek)2 DayOfWeek.Tuesday Expression Casts 2 to DayOfWeek.Tuesday
(DayOfWeek)3 DayOfWeek.Wednesday Expression Casts 3 to DayOfWeek.Wednesday
(DayOfWeek)4 DayOfWeek.Thursday Expression Casts 4 to DayOfWeek.Thursday
(DayOfWeek)5 DayOfWeek.Friday Expression Casts 5 to DayOfWeek.Friday
(DayOfWeek)6 DayOfWeek.Saturday Expression Casts 6 to DayOfWeek.Saturday
Use Enum.Parse (DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Sunday") DayOfWeek.Sunday Expression Parses "Sunday" and converts it to DayOfWeek.Sunday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Monday") DayOfWeek.Monday Expression Parses "Monday" and converts it to DayOfWeek.Monday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Tuesday") DayOfWeek.Tuesday Expression Parses "Tuesday" and converts it to DayOfWeek.Tuesday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Wednesday") DayOfWeek.Wednesday Expression Parses "Wednesday" and converts it to DayOfWeek.Wednesday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Thursday") DayOfWeek.Thursday Expression Parses "Thursday" and converts it to DayOfWeek.Thursday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Friday") DayOfWeek.Friday Expression Parses "Friday" and converts it to DayOfWeek.Friday. See Enum.Parse
(DayOfWeek)Enum.Parse(typeof(DayOfWeek), "Saturday") DayOfWeek.Saturday Expression Parses "Saturday" and converts it to DayOfWeek.Saturday. See Enum.Parse
Use Enum.ToObject (DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 0) DayOfWeek.Sunday Expression Converts 0 to DayOfWeek.Sunday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 1) DayOfWeek.Monday Expression Converts 1 to DayOfWeek.Monday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 2) DayOfWeek.Tuesday Expression Converts 2 to DayOfWeek.Tuesday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 3) DayOfWeek.Wednesday Expression Converts 3 to DayOfWeek.Wednesday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 4) DayOfWeek.Thursday Expression Converts 4 to DayOfWeek.Thursday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 5) DayOfWeek.Friday Expression Converts 5 to DayOfWeek.Friday value. See Enum.ToObject
(DayOfWeek)Enum.ToObject(typeof(DayOfWeek), 6) DayOfWeek.Saturday Expression Converts 6 to DayOfWeek.Saturday value. See Enum.ToObject

Please see Instantiating an enumeration type for further information.

Convert DayOfWeek to Text

The following table shows some of the ways that a DayOfWeek can be converted to text.

Method Example Result Editor Support Notes
Use ToString DayOfWeek.Sunday.ToString() "Sunday" Expression Converts DayOfWeek.Sunday to "Sunday". See Enum.ToString
DayOfWeek.Monday.ToString() "Monday" Expression Converts DayOfWeek.Monday to "Monday". See Enum.ToString
DayOfWeek.Tuesday.ToString() "Tuesday" Expression Converts DayOfWeek.Tuesday to "Tuesday". See Enum.ToString
DayOfWeek.Wednesday.ToString() "Wednesday" Expression Converts DayOfWeek.Wednesday to "Wednesday". See Enum.ToString
DayOfWeek.Thursday.ToString() "Thursday" Expression Converts DayOfWeek.Thursday to "Thursday". See Enum.ToString
DayOfWeek.Friday.ToString() "Friday" Expression Converts DayOfWeek.Friday to "Friday". See Enum.ToString
DayOfWeek.Saturday.ToString() "Saturday" Expression Converts DayOfWeek.Saturday to "Saturday". See Enum.ToString
Use Convert.ToString Convert.ToString(DayOfWeek.Sunday) "Sunday" Expression Converts DayOfWeek.Sunday to "Sunday". See Convert.ToString
Convert.ToString(DayOfWeek.Monday) "Monday" Expression Converts DayOfWeek.Monday to "Monday". See Convert.ToString
Convert.ToString(DayOfWeek.Tuesday) "Tuesday" Expression Converts DayOfWeek.Tuesday to "Tuesday". See Convert.ToString
Convert.ToString(DayOfWeek.Wednesday) "Wednesday" Expression Converts DayOfWeek.Wednesday to "Wednesday". See Convert.ToString
Convert.ToString(DayOfWeek.Thursday) "Thursday" Expression Converts DayOfWeek.Thursday to "Thursday". See Convert.ToString
Convert.ToString(DayOfWeek.Friday) "Friday" Expression Converts DayOfWeek.Friday to "Friday". See Convert.ToString
Convert.ToString(DayOfWeek.Saturday) "Saturday" Expression Converts DayOfWeek.Saturday to "Saturday". See Convert.ToString
Use Convert Object To Text block where Object property has a value of DayOfWeek.Sunday "Sunday" N/A Converts DayOfWeek.Sunday to "Sunday". See Convert Object To Text
where Object property has a value of DayOfWeek.Monday "Monday" N/A Converts DayOfWeek.Monday to "Monday". See Convert Object To Text
where Object property has a value of DayOfWeek.Tuesday "Tuesday" N/A Converts DayOfWeek.Tuesday to "Tuesday". See Convert Object To Text
where Object property has a value of DayOfWeek.Wednesday "Wednesday" N/A Converts DayOfWeek.Wednesday to "Wednesday". See Convert Object To Text
where Object property has a value of DayOfWeek.Thursday "Thursday" N/A Converts DayOfWeek.Thursday to "Thursday". See Convert Object To Text
where Object property has a value of DayOfWeek.Friday "Friday" N/A Converts DayOfWeek.Friday to "Friday". See Convert Object To Text
where Object property has a value of DayOfWeek.Saturday "Saturday" N/A Converts DayOfWeek.Saturday to "Saturday". See Convert Object To Text
Use Convert Object To Json block where Object property has a value of DayOfWeek.Sunday "0" N/A Converts DayOfWeek.Sunday to "0". See Convert Object To Json
where Object property has a value of DayOfWeek.Monday "1" N/A Converts DayOfWeek.Monday to "1". See Convert Object To Json
where Object property has a value of DayOfWeek.Tuesday "2" N/A Converts DayOfWeek.Tuesday to "2". See Convert Object To Json
where Object property has a value of DayOfWeek.Wednesday "3" N/A Converts DayOfWeek.Wednesday to "3". See Convert Object To Json
where Object property has a value of DayOfWeek.Thursday "4" N/A Converts DayOfWeek.Thursday to "4". See Convert Object To Json
where Object property has a value of DayOfWeek.Friday "5" N/A Converts DayOfWeek.Friday to "5". See Convert Object To Json
where Object property has a value of DayOfWeek.Saturday "6" N/A Converts DayOfWeek.Saturday to "6". See Convert Object To Json

Please see Formatting enumeration values for further information.

Convert DayOfWeek to a Number

The following table shows some of the ways that a DayOfWeek can be converted to a number.

Method Example Result Editor Support Notes
Use Explicit Casting (Int32)DayOfWeek.Sunday 0 Expression Casts DayOfWeek.Sunday to 0
(Int32)DayOfWeek.Monday 1 Expression Casts DayOfWeek.Monday to 1
(Int32)DayOfWeek.Tuesday 2 Expression Casts DayOfWeek.Tuesday to 2
(Int32)DayOfWeek.Wednesday 3 Expression Casts DayOfWeek.Wednesday to 3
(Int32)DayOfWeek.Thursday 4 Expression Casts DayOfWeek.Thursday to 4
(Int32)DayOfWeek.Friday 5 Expression Casts DayOfWeek.Friday to 5
(Int32)DayOfWeek.Saturday 6 Expression Casts DayOfWeek.Saturday to 6
Use Convert.ToInt32 Convert.ToInt32(DayOfWeek.Sunday) 0 Expression Converts DayOfWeek.Sunday to 0. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Monday) 1 Expression Converts DayOfWeek.Monday to 1. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Tuesday) 2 Expression Converts DayOfWeek.Tuesday to 2. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Wednesday) 3 Expression Converts DayOfWeek.Wednesday to 3. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Thursday) 4 Expression Converts DayOfWeek.Thursday to 4. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Friday) 5 Expression Converts DayOfWeek.Friday to 5. See Convert.ToInt32
Convert.ToInt32(DayOfWeek.Saturday) 6 Expression Converts DayOfWeek.Saturday to 6. See Convert.ToInt32

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is DayOfWeek.
  • The Literal Editor is available for Input properties where the data type is DayOfWeek.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is DayOfWeek.

Known Limitations

None

See Also

External Documentation

6.4.6.5 - TimePeriod

Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of years, months, days, hours, minutes, seconds, and milliseconds.

TimePeriod

(Cortex.DataTypes.DateAndTime.TimePeriod)

Summary

Properties

Years

Months

Days

Hours

Minutes

Seconds

Milliseconds

Remarks

Create a TimePeriod

Convert TimePeriod to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.6.6 - TimeSpan

Used to represent a time interval (duration of time or elapsed time) that is measured as a positive or negative number of days, hours, minutes, seconds, and milliseconds. It can be used wherever a TimePeriod is expected, and wll be converted to a TimePeriod automatically.

TimeSpan

(System.TimeSpan)

Summary

Remarks

Create a TimeSpan

Convert TimeSpan to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.7 - Email

Data types used for working with emails and connecting to mail servers.

6.4.7.1 - Authentication

Data types used for authenticating with mail servers.

6.4.7.1.1 - EmailCredentials

Used to represent details required to authenticate with a mail server.

EmailCredentials

(Cortex.DataTypes.Email.Authentication.EmailCredentials)

6.4.7.1.2 - EmailUserCredentials

Used to represent details required to authenticate with a mail server.

EmailUserCredentials

(Cortex.DataTypes.Email.Authentication.EmailUserCredentials)

6.4.7.1.3 - IEmailCredentials

Any data type used to represent details required to authenticate with a mail server.

IEmailCredentials

(Cortex.DataTypes.Email.Authentication.IEmailCredentials)

6.4.7.2 - BasicEmailSessionDetails

Used to represent configuration for opening and maintaining a session with a mail server.

BasicEmailSessionDetails

(Cortex.DataTypes.Email.BasicEmailSessionDetails)

Summary

The BasicEmailSessionDetails data type is used to represent configuration for opening and maintaining a session with a mail server.

Category: Email
Name: BasicEmailSessionDetails
Full Name: Cortex.DataTypes.Email.BasicEmailSessionDetails
Alias: N/A
Description: Configuration for opening and maintaining a session with a mail server.
Default Value: null
Can be used as: BasicEmailSessionDetails, Object, dynamic
Can be cast to: N/A

Properties

ServerDetails

The ServerDetails are used to configure the Host and Port of the mail server to connect to and whether or not to UseSsl.

Data Type ServerDetails
Is Advanced false
Default Editor Literal
Default Value ServerDetails with value shown below:
{ 
    "Host": "",
    "Port": 465,
    "UseSsl": true
}

Credentials

The Credentials are used to configure the Username and Password used for authentication.

Data Type UserCredentials
Is Advanced false
Default Editor Literal
Default Value UserCredentials with value shown below:
{ 
    "Domain": "",
    "Username": "",
    "Password": ""
}

Remarks

Create a BasicEmailSessionDetails

The following table shows some of the ways that BasicEmailSessionDetails can be created.

Method Example Result Editor Support Notes
Use a BasicEmailSessionDetails constructor new BasicEmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword")) {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}} Expression The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the Password, see EncryptedText.

A BasicEmailSessionDetails can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
ServerDetails ServerDetails Host: "smtp.gmail.com"
Port: 465
UseSsl: true
The ServerDetails that are used to connect to the server.
Credentials UserCredentials Domain: ""
Username: "sender@gmail.com"
Password: "encryptedPassword"
The Credentials that are used for authentication on the server.

The Password property in the UserCredentials must be encrypted, for more information on how to encrypt the Password, see EncryptedText.

Convert BasicEmailSessionDetails to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}} "{\r\n \"ServerDetails\": {\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n },\r\n \"Credentials\": {\r\n \"Domain\": null,\r\n \"Username\": \"sender@gmail.com\",\r\n \"Password\": \"encryptedPassword\"\r\n }\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is BasicEmailSessionDetails.
  • The Literal Editor is available for Input properties where the data type is BasicEmailSessionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is BasicEmailSessionDetails.

Known Limitations

Currently, this data type is not compatible for use with unauthenticated mail servers.

This limitation may be removed in the future.

See Also

External Documentation

None

6.4.7.3 - EmailAddress

Used to represent an email address.

EmailAddress

(Cortex.DataTypes.Email.EmailAddress)

Summary

The EmailAddress data type is used to represent an email address.

Category: Email
Name: EmailAddress
Full Name: Cortex.DataTypes.Email.EmailAddress
Alias: N/A
Description: An email address.
Default Value: null
Can be used as: EmailAddress, Object, dynamic
Can be cast to: N/A

Properties

Name

Name is used to define the display name associated with the email address.

This property is not required.

Data Type String
Is Advanced true
Default Editor Literal
Default Value String with value ""

Address

Address is used to define the email address. This must be a valid email address as outlined in RFC 5321.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value ""

Remarks

Create an EmailAddress

The following table shows some of the ways that an EmailAddress can be created.

Method Example Result Editor Support Notes
Use an EmailAddress constructor new EmailAddress(name: "Sender", address: "sender@outlook.com") {"Name": "Sender", "Address": "sender@outlook.com"} Expression Name specified
new EmailAddress(address: "sender@outlook.com") {"Name": null, "Address": "sender@outlook.com"} Expression Name not specified

An EmailAddress can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
Name String "Sender" Name defines the display name associated with the email address.
Address String "sender@outlook.com" Address defines the email address.

Convert EmailAddress to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"Name": "Sender", "Address": "sender@outlook.com"} "{\r\n \"Name\": \"Sender\",\r\n \"Address\": \"sender@outlook.com\"\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is EmailAddress.
  • The Literal Editor is available for Input properties where the data type is EmailAddress.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is EmailAddress.

Known Limitations

None

See Also

External Documentation

6.4.7.4 - EmailMessage

Used to represent an email message.

EmailMessage

(Cortex.DataTypes.Email.EmailMessage)

Summary

The EmailMessage data type is used to represent an email message.

Category: Email
Name: EmailMessage
Full Name: Cortex.DataTypes.Email.EmailMessage
Alias: N/A
Description: An email message.
Default Value: null
Can be used as: EmailMessage, Object, dynamic
Can be cast to: N/A

Properties

To

To is used to define the list of recipients for the email message.

Data Type IList<EmailAddress>
Is Advanced false
Default Editor Expression
Default Value IList<EmailAddress> with value new List<EmailAddress>(){ new EmailAddress("") }

From

From is used to define the sender of the email message.

Data Type EmailAddress
Is Advanced false
Default Editor Literal
Default Value EmailAddress with value shown below:
{
    "Name": "",
    "Address": ""
}

Cc

Cc is used to define the list of CC recipients for the email message.

Data Type IList<EmailAddress>
Is Advanced true
Default Editor Expression
Default Value IList<EmailAddress> with value null

Bcc

Bcc is used to define the list of BCC recipients for the email message.

Data Type IList<EmailAddress>
Is Advanced true
Default Editor Expression
Default Value IList<EmailAddress> with value null

Priority

Priority is used to define the priority of the email message, for more information on the range of values this can take, see EmailMessagePriority.

Data Type EmailMessagePriority
Is Advanced true
Default Editor Literal
Default Value EmailMessagePriority with value EmailMessagePriority.Normal

Subject

Subject is used to define the subject of the email message.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value ""

BodyFormat

BodyFormat is used to define the format of the email body, for more information on the range of values this can take, see EmailMessageBodyFormat.

Data Type EmailMessageBodyFormat
Is Advanced true
Default Editor Literal
Default Value EmailMessageBodyFormat with value EmailMessageBodyFormat.Text

Body

The Body is used to define the body of the email message.

Data Type String
Is Advanced false
Default Editor Expression
Default Value String with value $@""

Attachments

The Attachments is used to define the list of attachments for the email message, where each item in the list is a path pointing to the attachment.

The supported file path formats are dependent on the block being used:

Data Type IList<String>
Is Advanced true
Default Editor Expression
Default Value IList<String> with value null

Remarks

Create an EmailMessage

The following table shows some of the ways that an EmailMessage can be created.

Method Example Result Editor Support Notes
Use an EmailMessage constructor new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: null, bcc: null, priority: null, subject: "Example email subject", bodyFormat: null, body: "Example email body", attachments: null) {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [], "Bcc": [], "Priority": null, "Subject": "Example email subject", "BodyFormat": null, "Body": "Example email body", "Attachments": []} Expression No Advanced Properties properties configured
new EmailMessage(to: new List<EmailAddress>(){ new EmailAddress("recipient@outlook.com") }, from: new EmailAddress("sender@outlook.com"), cc: new List<EmailAddress>(){ new EmailAddress("cc@outlook.com") }, bcc: new List<EmailAddress>(){ new EmailAddress("bcc@outlook.com") }, priority: EmailMessagePriority.Urgent, subject: "Example email subject", bodyFormat: EmailMessageBodyFormat.Text, body: "Example email body", attachments: new List<string>(){ @"C:\attachment.txt" }) {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Text", "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]} Expression All Advanced Properties properties configured

An EmailMessage can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
To IList<EmailAddress> new List<EmailAddress>(){ "recipient@outlook.com" } To defines a list of recipients for the email message.
From EmailAddress Name: Sender
Address: sender@outlook.com
From defines the sender of the email message.
Cc IList<EmailAddress> new List<EmailAddress>(){ "cc@outlook.com" } Cc defines a list of CC recipients for the email message.
Bcc IList<EmailAddress> new List<EmailAddress>(){ "bcc@outlook.com" } Bcc defines a list of BCC recipients for the email message.
Priority EmailMessagePriority Normal Priority defines the priority of the email message.
Subject String Example subject Subject defines the subject of the email message.
BodyFormat EmailMessageBodyFormat Text BodyFormat defines the format of the email message body.
Body String $@"Example body" Body defines the body of the email message.
Attachments IList<String> new List<string>(){ @"C:\attachment.txt" } Attachments defines the list of attachments for the email message.

Convert EmailMessage to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"To": [{"Name": null, "Address": "recipient@outlook.com"}], "From": {"Name": null, "Address": "sender@outlook.com"}, "Cc": [{"Name": null, "Address": "cc@outlook.com"}], "Bcc": [{"Name": null, "Address": "bcc@outlook.com"}], "Priority": "EmailMessagePriority.Urgent", "Subject": "Example email subject", "BodyFormat": "EmailMessageBodyFormat.Text", "Body": "Example email body", "Attachments": ["C:\\attachment.txt"]} "{\r\n \"To\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"recipient@outlook.com\"\r\n }\r\n ],\r\n \"From\": {\r\n \"Name\": null,\r\n \"Address\": \"sender@outlook.com\"\r\n },\r\n \"Cc\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"cc@outlook.com\"\r\n }\r\n ],\r\n \"Bcc\": [\r\n {\r\n \"Name\": null,\r\n \"Address\": \"bcc@outlook.com\"\r\n }\r\n ],\r\n \"Priority\": 2,\r\n \"Subject\": \"Example email subject\",\r\n \"BodyFormat\": 0,\r\n \"Body\": \"Example email body\",\r\n \"Attachments\": [\r\n \"C:\\attachment.txt\"\r\n ]\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is EmailMessage.
  • The Literal Editor is available for Input properties where the data type is EmailMessage.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is EmailMessage.

Known Limitations

None

See Also

External Documentation

None

6.4.7.5 - EmailMessageBodyFormat

Used to represent the format of an email message body.

EmailMessageBodyFormat

(Cortex.DataTypes.Email.EmailMessageBodyFormat)

Summary

The EmailMessageBodyFormat data type is used to represent the format of an email message body.

EmailMessageBodyFormat is an enum data type, which means it has a defined set of values, where each value has an associated String name and Int32 value.

Category: Email
Name: EmailMessageBodyFormat
Full Name: Cortex.DataTypes.Email.EmailMessageBodyFormat
Alias: N/A
Description: Format of an email message body.
Size: 4 bytes
Default Value: EmailMessageBodyFormat.Text
Can be used as: EmailMessageBodyFormat, Object, dynamic
Can be cast to: Int16 (e.g. (Int16)EmailMessageBodyFormat.Text or (System.Int16)EmailMessageBodyFormat.Text or (short)EmailMessageBodyFormat.Text)
Int32 (e.g. (Int32)EmailMessageBodyFormat.Text or (System.Int32)EmailMessageBodyFormat.Text or (int)EmailMessageBodyFormat.Text)
Int64 (e.g. (Int64)EmailMessageBodyFormat.Text or (System.Int64)EmailMessageBodyFormat.Text or (long)EmailMessageBodyFormat.Text)
Single (e.g. (Single)EmailMessageBodyFormat.Text or (System.Single)EmailMessageBodyFormat.Text or (float)EmailMessageBodyFormat.Text)
Double (e.g. (Double)EmailMessageBodyFormat.Text or (System.Double)EmailMessageBodyFormat.Text or (double)EmailMessageBodyFormat.Text)

Values

Text

Name: Text
Value: Int32 with value 0
Notes: Used when an email message body format is plain text.

Html

Name: Html
Value: Int32 with value 1
Notes: Used when an email message body format is HTML.

Remarks

Create an EmailMessageBodyFormat

The following table shows some of the ways that EmailMessageBodyFormat can be created.

Method Example Result Editor Support Notes
Declare an EmailMessageBodyFormat literal Text EmailMessageBodyFormat.Text Literal Indicates Text
Html EmailMessageBodyFormat.Html Literal Indicates Html
Use an EmailMessageBodyFormat expression EmailMessageBodyFormat.Text EmailMessageBodyFormat.Text Expression Indicates Text
EmailMessageBodyFormat.Html EmailMessageBodyFormat.Html Expression Indicates Html
Use Explicit Casting (EmailMessageBodyFormat)0 EmailMessageBodyFormat.Text Expression Indicates Text
(EmailMessageBodyFormat)1 EmailMessageBodyFormat.Html Expression Indicates Html
Use Enum.Parse (EmailMessageBodyFormat)Enum.Parse(typeof(EmailMessageBodyFormat), "Text") EmailMessageBodyFormat.Text Expression Parses "Text" and converts it to EmailMessageBodyFormat.Text. See Enum.Parse
(EmailMessageBodyFormat)Enum.Parse(typeof(EmailMessageBodyFormat), "Html") EmailMessageBodyFormat.Html Expression Parses "Html" and converts it to EmailMessageBodyFormat.Html. See Enum.Parse
Use Enum.ToObject (EmailMessageBodyFormat)Enum.ToObject(typeof(EmailMessageBodyFormat), 0) EmailMessageBodyFormat.Text Expression Converts 0 to EmailMessageBodyFormat.Text value. See Enum.ToObject
(EmailMessageBodyFormat)Enum.ToObject(typeof(EmailMessageBodyFormat), 1) EmailMessageBodyFormat.Html Expression Converts 1 to EmailMessageBodyFormat.Html value. See Enum.ToObject

Please see Instantiating an enumeration type for further information.

Convert EmailMessageBodyFormat to Text

The following table shows some of the ways that a EmailMessageBodyFormat can be converted to text.

Method Example Result Editor Support Notes
Use ToString EmailMessageBodyFormat.Text.ToString() "Text" Expression Converts EmailMessageBodyFormat.Text to "Text". See Enum.ToString
EmailMessageBodyFormat.Html.ToString() "Html" Expression Converts EmailMessageBodyFormat.Html to "Html". See Enum.ToString
Use Convert.ToString Convert.ToString(EmailMessageBodyFormat.Text) "Text" Expression Converts EmailMessageBodyFormat.Text to "Text". See Convert.ToString
Convert.ToString(EmailMessageBodyFormat.Html) "Html" Expression Converts EmailMessageBodyFormat.Html to "Html". See Convert.ToString
Use Convert Object To Text block where Object property has a value of EmailMessageBodyFormat.Text "Text" N/A Converts EmailMessageBodyFormat.Text to "Text". See Convert Object To Text
where Object property has a value of EmailMessageBodyFormat.Html "Html" N/A Converts EmailMessageBodyFormat.Html to "Html". See Convert Object To Text
Use Convert Object To Json block where Object property has a value of EmailMessageBodyFormat.Text "0" N/A Converts EmailMessageBodyFormat.Text to "0". See Convert Object To Json
where Object property has a value of EmailMessageBodyFormat.Html "1" N/A Converts EmailMessageBodyFormat.Html to "1". See Convert Object To Json

Please see Formatting enumeration values for further information.

Convert EmailMessageBodyFormat to a Number

The following table shows some of the ways that a EmailMessageBodyFormat can be converted to a number.

Method Example Result Editor Support Notes
Use Explicit Casting (Int32)EmailMessageBodyFormat.Text 0 Expression Casts EmailMessageBodyFormat.Text to 0
(Int32)EmailMessageBodyFormat.Html 1 Expression Casts EmailMessageBodyFormat.Html to 1
Use Convert.ToInt32 Convert.ToInt32(EmailMessageBodyFormat.Text) 0 Expression Converts EmailMessageBodyFormat.Text to 0. See Convert.ToInt32
Convert.ToInt32(EmailMessageBodyFormat.Html) 1 Expression Converts EmailMessageBodyFormat.Html to 1. See Convert.ToInt32

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is EmailMessageBodyFormat.
  • The Literal Editor is available for Input properties where the data type is EmailMessageBodyFormat.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is EmailMessageBodyFormat.

Known Limitations

None

See Also

External Documentation

6.4.7.6 - EmailMessagePriority

Used to represent the priority of an email message.

EmailMessagePriority

(Cortex.DataTypes.Email.EmailMessagePriority)

Summary

The EmailMessagePriority data type is used to represent the priority of an email message.

EmailMessagePriority is an enum data type, which means it has a defined set of values, where each value has an associated String name and Int32 value.

Category: Email
Name: EmailMessagePriority
Full Name: Cortex.DataTypes.Email.EmailMessagePriority
Alias: N/A
Description: Priority of an email message.
Size: 4 bytes
Default Value: EmailMessagePriority.Normal
Can be used as: EmailMessagePriority, Object, dynamic
Can be cast to: Int16 (e.g. (Int16)EmailMessagePriority.Normal or (System.Int16)EmailMessagePriority.Normal or (short)EmailMessagePriority.Normal)
Int32 (e.g. (Int32)EmailMessagePriority.Normal or (System.Int32)EmailMessagePriority.Normal or (int)EmailMessagePriority.Normal)
Int64 (e.g. (Int64)EmailMessagePriority.Normal or (System.Int64)EmailMessagePriority.Normal or (long)EmailMessagePriority.Normal)
Single (e.g. (Single)EmailMessagePriority.Normal or (System.Single)EmailMessagePriority.Normal or (float)EmailMessagePriority.Normal)
Double (e.g. (Double)EmailMessagePriority.Normal or (System.Double)EmailMessagePriority.Normal or (double)EmailMessagePriority.Normal)

Values

Normal

Name: Normal
Value: Int32 with value 0
Notes: Used when an email is marked with normal priority.

NonUrgent

Name: NonUrgent
Value: Int32 with value 1
Notes: Used when an email is marked with non-urgent priority.

Urgent

Name: Urgent
Value: Int32 with value 2
Notes: Used when an email is marked with urgent priority.

Remarks

Create an EmailMessagePriority

The following table shows some of the ways that EmailMessagePriority can be created.

Method Example Result Editor Support Notes
Declare an EmailMessagePriority literal Normal EmailMessagePriority.Normal Literal Indicates Normal
NonUrgent EmailMessagePriority.NonUrgent Literal Indicates NonUrgent
Urgent EmailMessagePriority.Urgent Literal Indicates Urgent
Use an EmailMessagePriority expression EmailMessagePriority.Normal EmailMessagePriority.Normal Expression Indicates Normal
EmailMessagePriority.NonUrgent EmailMessagePriority.NonUrgent Expression Indicates NonUrgent
EmailMessagePriority.Urgent EmailMessagePriority.Urgent Expression Indicates Urgent
Use Explicit Casting (EmailMessagePriority)0 EmailMessagePriority.Normal Expression Indicates Normal
(EmailMessagePriority)1 EmailMessagePriority.NonUrgent Expression Indicates NonUrgent
(EmailMessagePriority)2 EmailMessagePriority.Urgent Expression Indicates Urgent
Use Enum.Parse (EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "Normal") EmailMessagePriority.Normal Expression Parses "Normal" and converts it to EmailMessagePriority.Normal. See Enum.Parse
(EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "NonUrgent") EmailMessagePriority.NonUrgent Expression Parses "NonUrgent" and converts it to EmailMessagePriority.NonUrgent. See Enum.Parse
(EmailMessagePriority)Enum.Parse(typeof(EmailMessagePriority), "Urgent") EmailMessagePriority.Urgent Expression Parses "Urgent" and converts it to EmailMessagePriority.Urgent. See Enum.Parse
Use Enum.ToObject (EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 0) EmailMessagePriority.Normal Expression Converts 0 to EmailMessagePriority.Normal value. See Enum.ToObject
(EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 1) EmailMessagePriority.NonUrgent Expression Converts 1 to EmailMessagePriority.NonUrgent value. See Enum.ToObject
(EmailMessagePriority)Enum.ToObject(typeof(EmailMessagePriority), 2) EmailMessagePriority.Urgent Expression Converts 2 to EmailMessagePriority.Urgent value. See Enum.ToObject

Please see Instantiating an enumeration type for further information.

Convert EmailMessagePriority to Text

The following table shows some of the ways that a EmailMessagePriority can be converted to text.

Method Example Result Editor Support Notes
Use ToString EmailMessagePriority.Normal.ToString() "Normal" Expression Converts EmailMessagePriority.Normal to "Normal". See Enum.ToString
EmailMessagePriority.NonUrgent.ToString() "NonUrgent" Expression Converts EmailMessagePriority.NonUrgent to "NonUrgent". See Enum.ToString
EmailMessagePriority.Urgent.ToString() "Urgent" Expression Converts EmailMessagePriority.Urgent to "Urgent". See Enum.ToString
Use Convert.ToString Convert.ToString(EmailMessagePriority.Normal) "Normal" Expression Converts EmailMessagePriority.Normal to "Normal". See Convert.ToString
Convert.ToString(EmailMessagePriority.NonUrgent) "NonUrgent" Expression Converts EmailMessagePriority.NonUrgent to "NonUrgent". See Convert.ToString
Convert.ToString(EmailMessagePriority.Urgent) "Urgent" Expression Converts EmailMessagePriority.Urgent to "Urgent". See Convert.ToString
Use Convert Object To Text block where Object property has a value of EmailMessagePriority.Normal "Normal" N/A Converts EmailMessagePriority.Normal to "Normal". See Convert Object To Text
where Object property has a value of EmailMessagePriority.NonUrgent "NonUrgent" N/A Converts EmailMessagePriority.NonUrgent to "NonUrgent". See Convert Object To Text
where Object property has a value of EmailMessagePriority.Urgent "Urgent" N/A Converts EmailMessagePriority.Urgent to "Urgent". See Convert Object To Text
Use Convert Object To Json block where Object property has a value of EmailMessagePriority.Normal "0" N/A Converts EmailMessagePriority.Normal to "0". See Convert Object To Json
where Object property has a value of EmailMessagePriority.NonUrgent "1" N/A Converts EmailMessagePriority.NonUrgent to "1". See Convert Object To Json
where Object property has a value of EmailMessagePriority.Urgent "2" N/A Converts EmailMessagePriority.Urgent to "2". See Convert Object To Json

Please see Formatting enumeration values for further information.

Convert EmailMessagePriority to a Number

The following table shows some of the ways that a EmailMessagePriority can be converted to a number.

Method Example Result Editor Support Notes
Use Explicit Casting (Int32)EmailMessagePriority.Normal 0 Expression Casts EmailMessagePriority.Normal to 0
(Int32)EmailMessagePriority.NonUrgent 1 Expression Casts EmailMessagePriority.NonUrgent to 1
(Int32)EmailMessagePriority.Urgent 2 Expression Casts EmailMessagePriority.Urgent to 2
Use Convert.ToInt32 Convert.ToInt32(EmailMessagePriority.Normal) 0 Expression Converts EmailMessagePriority.Normal to 0. See Convert.ToInt32
Convert.ToInt32(EmailMessagePriority.NonUrgent) 1 Expression Converts EmailMessagePriority.NonUrgent to 1. See Convert.ToInt32
Convert.ToInt32(EmailMessagePriority.Urgent) 2 Expression Converts EmailMessagePriority.Urgent to 2. See Convert.ToInt32

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is EmailMessagePriority.
  • The Literal Editor is available for Input properties where the data type is EmailMessagePriority.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is EmailMessagePriority.

Known Limitations

None

See Also

External Documentation

6.4.7.7 - EmailSessionErrorCode

Used to represent an error code explaining the reason an EmailSessionException occurred.

EmailSessionErrorCode

(Cortex.DataTypes.Email.EmailSessionErrorCode)

Summary

The EmailSessionErrorCode data type is used to represent an error code explaining the reason an EmailSessionException occurred. For more information on the exception itself, see EmailSessionException.

EmailSessionErrorCode is an enum data type, which means it has a defined set of values, where each value has an associated String name and Int32 value.

Category: Email
Name: EmailSessionErrorCode
Full Name: Cortex.DataTypes.Email.EmailSessionErrorCode
Alias: N/A
Description: Error code explaining the reason an EmailSessionException occurred.
Size: 4 bytes
Default Value: (EmailSessionErrorCode)0
Can be used as: EmailSessionErrorCode, Object, dynamic
Can be cast to: Int16 (e.g. (Int16)EmailSessionErrorCode.InvalidPort or (System.Int16)EmailSessionErrorCode.InvalidPort or (short)EmailSessionErrorCode.InvalidPort)
Int32 (e.g. (Int32)EmailSessionErrorCode.InvalidPort or (System.Int32)EmailSessionErrorCode.InvalidPort or (int)EmailSessionErrorCode.InvalidPort)
Int64 (e.g. (Int64)EmailSessionErrorCode.InvalidPort or (System.Int64)EmailSessionErrorCode.InvalidPort or (long)EmailSessionErrorCode.InvalidPort)
Single (e.g. (Single)EmailSessionErrorCode.InvalidPort or (System.Single)EmailSessionErrorCode.InvalidPort or (float)EmailSessionErrorCode.InvalidPort)
Double (e.g. (Double)EmailSessionErrorCode.InvalidPort or (System.Double)EmailSessionErrorCode.InvalidPort or (double)EmailSessionErrorCode.InvalidPort)

Values

InvalidPort

Name: InvalidPort
Value: Int32 with value 100
Notes: Used when an EmailSessionException occured due to an invalid Port being provided in ServerDetails. See Invalid Port.

InvalidHost

Name: InvalidHost
Value: Int32 with value 101
Notes: Used when an EmailSessionException occured due to an invalid Host being provided in ServerDetails. See Invalid Host.

SslRequired

Name: SslRequired
Value: Int32 with value 200
Notes: Used when an EmailSessionException occured due to UseSsl being set to false in ServerDetails when trying to establish a connection on a Port which requires SSL. See SSL Required.

SslUnsupported

Name: SslUnsupported
Value: Int32 with value 201
Notes: Used when an EmailSessionException occured due to UseSsl being set to true in ServerDetails when trying to establish a connection on a Port which does not support SSL. See SSL Unsupported.

InvalidUserCredentials

Name: InvalidUserCredentials
Value: Int32 with value 300
Notes: Used when an EmailSessionException occured due to an invalid Username and Password combination being provided in UserCredentials. See Invalid User Credentials.

InvalidCertificate

Name: InvalidCertificate
Value: Int32 with value 400
Notes: Used when an EmailSessionException occured due to an invalid CertificatePath and CertificatePassword combination being provided in GmailOAuthCertificateCredentials. See Invalid SSL Certificate.

InvalidGmailClientCredentials

Name: InvalidGmailClientCredentials
Value: Int32 with value 401
Notes: Used when an EmailSessionException occured due to an invalid FromAddress and ClientId combination being provided in GmailOAuthCertificateCredentials. See Invalid Gmail Client Credentials.

Remarks

Create an EmailSessionErrorCode

The following table shows some of the ways that EmailSessionErrorCode can be created.

Method Example Result Editor Support Notes
Use an EmailSessionErrorCode expression EmailSessionErrorCode.InvalidPort EmailSessionErrorCode.InvalidPort Expression Indicates an EmailSessionException occured due to an invalid Port being provided in ServerDetails
EmailSessionErrorCode.InvalidHost EmailSessionErrorCode.InvalidHost Expression Indicates an EmailSessionException occured due to an invalid Host being provided in ServerDetails
EmailSessionErrorCode.SslRequired EmailSessionErrorCode.SslRequired Expression Indicates an EmailSessionException occured due to UseSsl being set to false in ServerDetails when trying to establish a connection on a Port which requires SSL
EmailSessionErrorCode.SslUnsupported EmailSessionErrorCode.SslUnsupported Expression Indicates an EmailSessionException occured due to UseSsl being set to true in ServerDetails when trying to establish a connection on a Port which does not support SSL
EmailSessionErrorCode.InvalidUserCredentials EmailSessionErrorCode.InvalidUserCredentials Expression Indicates an EmailSessionException occured due to an invalid Username and Password combination being provided in UserCredentials
EmailSessionErrorCode.InvalidCertificate EmailSessionErrorCode.InvalidCertificate Expression Indicates an EmailSessionException occured due to an invalid CertificatePath and CertificatePassword combination being provided in GmailOAuthCertificateCredentials
EmailSessionErrorCode.InvalidGmailClientCredentials EmailSessionErrorCode.InvalidGmailClientCredentials Expression Indicates an EmailSessionException occured due to an invalid FromAddress and ClientId combination being provided in GmailOAuthCertificateCredentials
Use Explicit Casting (EmailSessionErrorCode)100 EmailSessionErrorCode.InvalidPort Expression Indicates an EmailSessionException occured due to an invalid Port being provided in ServerDetails
(EmailSessionErrorCode)101 EmailSessionErrorCode.InvalidHost Expression Indicates an EmailSessionException occured due to an invalid Host being provided in ServerDetails
(EmailSessionErrorCode)200 EmailSessionErrorCode.SslRequired Expression Indicates an EmailSessionException occured due to UseSsl being set to false in ServerDetails when trying to establish a connection on a Port which requires SSL
(EmailSessionErrorCode)201 EmailSessionErrorCode.SslUnsupported Expression Indicates an EmailSessionException occured due to UseSsl being set to true in ServerDetails when trying to establish a connection on a Port which does not support SSL
(EmailSessionErrorCode)300 EmailSessionErrorCode.InvalidUserCredentials Expression Indicates an EmailSessionException occured due to an invalid Username and Password combination being provided in UserCredentials
(EmailSessionErrorCode)400 EmailSessionErrorCode.InvalidCertificate Expression Indicates an EmailSessionException occured due to an invalid CertificatePath and CertificatePassword combination being provided in GmailOAuthCertificateCredentials
(EmailSessionErrorCode)401 EmailSessionErrorCode.InvalidGmailClientCredentials Expression Indicates an EmailSessionException occured due to an invalid FromAddress and ClientId combination being provided in GmailOAuthCertificateCredentials
Use Enum.Parse (EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidPort") EmailSessionErrorCode.InvalidPort Expression Parses "InvalidPort" and converts it to EmailSessionErrorCode.InvalidPort. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidHost") EmailSessionErrorCode.InvalidHost Expression Parses "InvalidHost" and converts it to EmailSessionErrorCode.InvalidHost. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "SslRequired") EmailSessionErrorCode.SslRequired Expression Parses "SslRequired" and converts it to EmailSessionErrorCode.SslRequired. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "SslUnsupported") EmailSessionErrorCode.SslUnsupported Expression Parses "SslUnsupported" and converts it to EmailSessionErrorCode.SslUnsupported. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidUserCredentials") EmailSessionErrorCode.InvalidUserCredentials Expression Parses "InvalidUserCredentials" and converts it to EmailSessionErrorCode.InvalidUserCredentials. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidCertificate") EmailSessionErrorCode.InvalidCertificate Expression Parses "InvalidCertificate" and converts it to EmailSessionErrorCode.InvalidCertificate. See Enum.Parse
(EmailSessionErrorCode)Enum.Parse(typeof(EmailSessionErrorCode), "InvalidGmailClientCredentials") EmailSessionErrorCode.InvalidGmailClientCredentials Expression Parses "InvalidGmailClientCredentials" and converts it to EmailSessionErrorCode.InvalidGmailClientCredentials. See Enum.Parse
Use Enum.ToObject (EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 100) EmailSessionErrorCode.InvalidPort Expression Converts 100 to EmailSessionErrorCode.InvalidPort value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 101) EmailSessionErrorCode.InvalidHost Expression Converts 101 to EmailSessionErrorCode.InvalidHost value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 200) EmailSessionErrorCode.SslRequired Expression Converts 200 to EmailSessionErrorCode.SslRequired value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 201) EmailSessionErrorCode.SslUnsupported Expression Converts 201 to EmailSessionErrorCode.SslUnsupported value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 300) EmailSessionErrorCode.InvalidUserCredentials Expression Converts 300 to EmailSessionErrorCode.InvalidUserCredentials value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 400) EmailSessionErrorCode.InvalidCertificate Expression Converts 400 to EmailSessionErrorCode.InvalidCertificate value. See Enum.ToObject
(EmailSessionErrorCode)Enum.ToObject(typeof(EmailSessionErrorCode), 401) EmailSessionErrorCode.InvalidGmailClientCredentials Expression Converts 401 to EmailSessionErrorCode.InvalidGmailClientCredentials value. See Enum.ToObject

Please see Instantiating an enumeration type for further information.

Convert EmailSessionErrorCode to Text

The following table shows some of the ways that an EmailSessionErrorCode can be converted to text.

Method Example Result Editor Support Notes
Use ToString EmailSessionErrorCode.InvalidPort.ToString() "InvalidPort" Expression Converts EmailSessionErrorCode.InvalidPort to "InvalidPort". See Enum.ToString
EmailSessionErrorCode.InvalidHost.ToString() "InvalidHost" Expression Converts EmailSessionErrorCode.InvalidHost to "InvalidHost". See Enum.ToString
EmailSessionErrorCode.SslRequired.ToString() "SslRequired" Expression Converts EmailSessionErrorCode.SslRequired to "SslRequired". See Enum.ToString
EmailSessionErrorCode.SslUnsupported.ToString() "SslUnsupported" Expression Converts EmailSessionErrorCode.SslUnsupported to "SslUnsupported". See Enum.ToString
EmailSessionErrorCode.InvalidUserCredentials.ToString() "InvalidUserCredentials" Expression Converts EmailSessionErrorCode.InvalidUserCredentials to "InvalidUserCredentials". See Enum.ToString
EmailSessionErrorCode.InvalidCertificate.ToString() "InvalidCertificate" Expression Converts EmailSessionErrorCode.InvalidCertificate to "InvalidCertificate". See Enum.ToString
EmailSessionErrorCode.InvalidGmailClientCredentials.ToString() "InvalidGmailClientCredentials" Expression Converts EmailSessionErrorCode.InvalidGmailClientCredentials to "InvalidGmailClientCredentials". See Enum.ToString
Use Convert.ToString Convert.ToString(EmailSessionErrorCode.InvalidPort) "InvalidPort" Expression Converts EmailSessionErrorCode.InvalidPort to "InvalidPort". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.InvalidHost) "InvalidHost" Expression Converts EmailSessionErrorCode.InvalidHost to "InvalidHost". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.SslRequired) "SslRequired" Expression Converts EmailSessionErrorCode.SslRequired to "SslRequired". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.SslUnsupported) "SslUnsupported" Expression Converts EmailSessionErrorCode.SslUnsupported to "SslUnsupported". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.InvalidUserCredentials) "InvalidUserCredentials" Expression Converts EmailSessionErrorCode.InvalidUserCredentials to "InvalidUserCredentials". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.InvalidCertificate) "InvalidCertificate" Expression Converts EmailSessionErrorCode.InvalidCertificate to "InvalidCertificate". See Convert.ToString
Convert.ToString(EmailSessionErrorCode.InvalidGmailClientCredentials) "InvalidGmailClientCredentials" Expression Converts EmailSessionErrorCode.InvalidGmailClientCredentials to "InvalidGmailClientCredentials". See Convert.ToString
Use Convert Object To Text block where Object property has a value of EmailSessionErrorCode.InvalidPort "InvalidPort" N/A Converts EmailSessionErrorCode.InvalidPort to "InvalidPort". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.InvalidHost "InvalidHost" N/A Converts EmailSessionErrorCode.InvalidHost to "InvalidHost". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.SslRequired "SslRequired" N/A Converts EmailSessionErrorCode.SslRequired to "SslRequired". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.SslUnsupported "SslUnsupported" N/A Converts EmailSessionErrorCode.SslUnsupported to "SslUnsupported". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.InvalidUserCredentials "InvalidUserCredentials" N/A Converts EmailSessionErrorCode.InvalidUserCredentials to "InvalidUserCredentials". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.InvalidCertificate "InvalidCertificate" N/A Converts EmailSessionErrorCode.InvalidCertificate to "InvalidCertificate". See Convert Object To Text
where Object property has a value of EmailSessionErrorCode.InvalidGmailClientCredentials "InvalidGmailClientCredentials" N/A Converts EmailSessionErrorCode.InvalidGmailClientCredentials to "InvalidGmailClientCredentials". See Convert Object To Text
Use Convert Object To Json block where Object property has a value of EmailSessionErrorCode.InvalidPort "100" N/A Converts EmailSessionErrorCode.InvalidPort to "100". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.InvalidHost "101" N/A Converts EmailSessionErrorCode.InvalidHost to "101". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.SslRequired "200" N/A Converts EmailSessionErrorCode.SslRequired to "200". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.SslUnsupported "201" N/A Converts EmailSessionErrorCode.SslUnsupported to "201". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.InvalidUserCredentials "300" N/A Converts EmailSessionErrorCode.InvalidUserCredentials to "300". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.InvalidCertificate "400" N/A Converts EmailSessionErrorCode.InvalidCertificate to "400". See Convert Object To Json
where Object property has a value of EmailSessionErrorCode.InvalidGmailClientCredentials "401" N/A Converts EmailSessionErrorCode.InvalidGmailClientCredentials to "401". See Convert Object To Json

Please see Formatting enumeration values for further information.

Convert EmailSessionErrorCode to a Number

The following table shows some of the ways that an EmailSessionErrorCode can be converted to a number.

Method Example Result Editor Support Notes
Use Explicit Casting (Int32)EmailSessionErrorCode.InvalidPort 100 Expression Casts EmailSessionErrorCode.InvalidPort to 100
(Int32)EmailSessionErrorCode.InvalidHost 101 Expression Casts EmailSessionErrorCode.InvalidHost to 101
(Int32)EmailSessionErrorCode.SslRequired 200 Expression Casts EmailSessionErrorCode.SslRequired to 200
(Int32)EmailSessionErrorCode.SslUnsupported 201 Expression Casts EmailSessionErrorCode.SslUnsupported to 201
(Int32)EmailSessionErrorCode.InvalidUserCredentials 300 Expression Casts EmailSessionErrorCode.InvalidUserCredentials to 300
(Int32)EmailSessionErrorCode.InvalidCertificate 400 Expression Casts EmailSessionErrorCode.InvalidCertificate to 400
(Int32)EmailSessionErrorCode.InvalidGmailClientCredentials 401 Expression Casts EmailSessionErrorCode.InvalidGmailClientCredentials to 401
Use Convert.ToInt32 Convert.ToInt32(EmailSessionErrorCode.InvalidPort) 100 Expression Converts EmailSessionErrorCode.InvalidPort to 100. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.InvalidHost) 101 Expression Converts EmailSessionErrorCode.InvalidHost to 101. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.SslRequired) 200 Expression Converts EmailSessionErrorCode.SslRequired to 200. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.SslUnsupported) 201 Expression Converts EmailSessionErrorCode.SslUnsupported to 201. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.InvalidUserCredentials) 300 Expression Converts EmailSessionErrorCode.InvalidUserCredentials to 300. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.InvalidCertificate) 400 Expression Converts EmailSessionErrorCode.InvalidCertificate to 400. See Convert.ToInt32
Convert.ToInt32(EmailSessionErrorCode.InvalidGmailClientCredentials) 401 Expression Converts EmailSessionErrorCode.InvalidGmailClientCredentials to 401. See Convert.ToInt32

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is EmailSessionErrorCode.
  • The Literal Editor is available for Input properties where the data type is EmailSessionErrorCode.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is EmailSessionErrorCode.

Known Limitations

Currently for the SslUnsupported error code, there are numerous reasons for why the exception may have occurred. For more information, see SSL Unsupported.

In the future this may change.

See Also

External Documentation

6.4.8 - Exceptions

Data types used for working with exceptions.

6.4.8.1 - Exception

The data type that all exceptions inherit from.

Exception

(System.Exception)

Summary

Remarks

Create an Exception

Convert Exception to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.9 - Files & Folders

Data types used for working with files and folders.

6.4.9.1 - ContentOptions

Used to define whether the Get Folder Content block should get file or folder paths.

ContentOptions

(Cortex.DataTypes.FilesAndFolders.ContentOptions)

Summary

Values

Files

Folders

Remarks

Create ContentOptions

Convert ContentOptions to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.9.2 - FileInformation

Used to represent information about a file.

FileInformation

(Cortex.DataTypes.FilesAndFolders.FileInformation)

Summary

Properties

Extension

Path

Name

ParentRoot

ParentPath

SizeInBytes

IsArchive

IsCompressed

IsEncrypted

IsHidden

IsNormal

IsTemporary

IsReadOnly

IsSystem

CreationTimeLocal

CreationTimeUtc

LastAccessTimeLocal

LastAccessTimeUtc

LastWriteTimeLocal

LastWriteTimeUtc

Remarks

Create a FileInformation

Convert FileInformation to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.9.3 - FileMatch

Used to represent a file matching a file search performed by the Search File and Search Files blocks.

FileMatch

(Cortex.DataTypes.FilesAndFolders.FileMatch)

Summary

Properties

FilePath

Line

Remarks

Create a FileMatch

Convert FileMatch to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.9.4 - FolderInformation

Used to represent information about a folder.

FolderInformation

(Cortex.DataTypes.FilesAndFolders.FolderInformation)

Summary

Properties

FileCount

FolderCount

TotalItemCount

Path

Name

ParentRoot

ParentPath

SizeInBytes

IsArchive

IsCompressed

IsEncrypted

IsHidden

IsNormal

IsTemporary

IsReadOnly

IsSystem

CreationTimeLocal

CreationTimeUtc

LastAccessTimeLocal

LastAccessTimeUtc

LastWriteTimeLocal

LastWriteTimeUtc

Remarks

Create a FolderInformation

Convert FolderInformation to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.10 - Flows

Data types used for working with Flows.

6.4.10.1 - FlowReference

Used to reference a Flow using its Id.

FlowReference

(Cortex.DataTypes.Flows.FlowReference)

Summary

A FlowReference is used to reference a flow that will be called using the Run Flow block.

Category: Flows
Name: FlowReference
Full Name: Cortex.DataTypes.Flows.FlowReference
Alias: N/A
Description: Used to reference a Flow using its Id.
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Properties

Id

The unique Id of the flow that is referenced.

Data Type Guid
Is Advanced false
Default Editor Literal
Default Value No value (defaults to 00000000-0000-0000-0000-000000000000)

Remarks

Create a FlowReference

Currently a FlowReference can only created by using the Flow Property of the Run Flow block. Using the editor to select a flow (by its Name or Id) will create a flow reference for the block to use.

Property Editor Support

  • The Expression Editor is not available for Input, InputOutput and Output properties where the data type is FlowReference.
  • The Literal Editor is available for Input properties where the data type is FlowReference.
  • The Variable Editor is available for Output properties where the data type is FlowReference.

Known limitations

None

See Also

External Documentation

None

6.4.10.2 - InputVariables

A collection of flow Input Variables.

InputVariables

(Cortex.DataTypes.Flows.InputVariables)

Summary

InputVariables are used to pass data into a called flow when using the Run Flow block.

Category: Flows
Name: InputVariables
Full Name: Cortex.DataTypes.Flows.InputVariables
Alias: N/A
Description: A collection of flow Input Variables.
Default Value: null
Can be used as: Structure, IDictionary<TKey, TItem>, IEnumerable, Object, dynamic
IEnumerable<KeyValuePair<TKey, TItem>> (e.g. where InputVariables is IDictionary<String, Object> and IEnumerable<KeyValuePair<TKey, TItem>> is IEnumerable<KeyValuePair<String, Object>>)
Can be cast to: N/A

Remarks

Create an InputVariables

The following table shows some of the ways that an InputVariables can be created.

Method Example Result Editor Support Notes
Use an InputVariables expression new InputVariables() {} Expression InputVariables containing zero items
new InputVariables() { { "Variable1", true } } { "Variable1": true } Expression InputVariables containing one Boolean item with a String key
new InputVariables() { { "Variable1", true }, { "Variable2", 100 } } { "Variable1": true, "Variable2": 100 } Expression InputVariables containing Boolean and Int32 items with String keys

An InputVariables can also be created using the Literal Editor when using the Run Flow block. For more information see the Inputs Property of the Run Flow block.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is InputVariables.
  • The Literal Editor is available for Input properties where the data type is InputVariables.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is InputVariables.

Known limitations

None

See Also

External Documentation

None

6.4.11 - Google Workspace

Data types used for working with Google Workspace blocks.

6.4.11.1 - Gmail

Data types used for working with Gmail blocks.

6.4.11.1.1 - Authentication

Data types used for authentication when working with Gmail blocks.

6.4.11.1.1.1 - OAuth

Data types used for authentication via OAuth when working with Gmail blocks.

6.4.11.1.1.1.1 - GmailOAuthCertificateCredentials

Used to represent configuration for authentication via OAuth when establishing a connection with a mail server hosted by Gmail.

GmailOAuthCertificateCredentials

(Cortex.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials)

Summary

The GmailOAuthCertificateCredentials data type is used to represent configuration for authentication via OAuth when establishing a connection with a mail server hosted by Gmail. For more information on how to set up a Gmail account so that this authentication mechanism can be used, see Setting up a Gmail account for OAuth authentication

Category: Gmail
Name: GmailOAuthCertificateCredentials
Full Name: Cortex.DataTypes.GoogleWorkspace.Gmail.Authentication.OAuth.GmailOAuthCertificateCredentials
Alias: N/A
Description: Configuration for authentication via OAuth when establishing a connection with a mail server hosted by Gmail.
Default Value: null
Can be used as: GmailOAuthCertificateCredentials, EmailCredentials, IEmailCredentials, Object, dynamic
Can be cast to: N/A

Properties

CertificatePath

The CertificatePath is used to define the path pointing to the certificate (.p12) file to be used for authentication via OAuth, the certificate file must be accessible from the server executing the flow. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value $@""

CertificatePassword

The CertificatePassword is used to define the password associated with the certificate file at the CertificatePath. This property is an EncryptedText and so it must be encrypted; for more information on how to encrypt the password, see EncryptedText.

Data Type EncryptedText
Is Advanced false
Default Editor Expression
Default Value EncryptedText with value ""

FromAddress

The FromAddress is used to define the address of the account used to set up the client application created to allow authentication via OAuth.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value ""

ClientId

The ClientId is used to define client ID of the client application created to allow authentication via OAuth. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value ""

Exceptions

The exceptions thrown by the data type can be found below:

Name Description
UnencryptedTextException Thrown when the CertificatePassword is not encrypted.

Remarks

Create a GmailOAuthCertificateCredentials

The following table shows how a GmailOAuthCertificateCredentials can be created.

Method Example Result Editor Support Notes
Use a GmailOAuthCertificateCredentials constructor new GmailOAuthCertificateCredentials(certificatePath: @"C:\certificate.p12", certificatePassword: "encryptedPassword", fromAddress: "sender@gmail.com", clientId: "clientId") {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"} Expression N/A

A GmailOAuthCertificateCredentials can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
CertificatePath EncryptableText $@"C:\certificate.p12" The CertificatePath defines the path pointing to the certificate (.p12) file to be used for authentication via OAuth.
CertificatePassword EncryptedText "encryptedPassword" The CertificatePassword defines the password associated with the certificate file at the CertificatePath.
FromAddress String "sender@gmail.com" The FromAddress defines the address of the account used to set up the client application created to allow authentication via OAuth.
ClientId EncryptableText "clientid" The ClientId defines the client ID of the client application created to allow authentication via OAuth.

Convert GmailOAuthCertificateCredentials to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"} "{\r\n \"CertificatePath\": \"C:\\\\certificate.p12\",\r\n \"CertificatePassword\": \"encryptedPassword\",\r\n \"FromAddress\": \"sender@gmail.com\",\r\n \"ClientId\": \"clientId\"\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is GmailOAuthCertificateCredentials.
  • The Literal Editor is available for Input properties where the data type is GmailOAuthCertificateCredentials.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is GmailOAuthCertificateCredentials.

Known Limitations

None

See Also

External Documentation

None

6.4.11.1.2 - GmailSessionDetails

Used to represent configuration for opening and maintaining a session with a mail server hosted by Gmail.

GmailSessionDetails

(Cortex.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails)

Summary

The GmailSessionDetails data type is used to represent configuration for opening and maintaining a session with a mail server hosted by Gmail.

Category: Gmail
Name: GmailSessionDetails
Full Name: Cortex.DataTypes.GoogleWorkspace.Gmail.GmailSessionDetails
Alias: N/A
Description: Configuration for opening and maintaining a session with a mail server hosted by Gmail.
Default Value: null
Can be used as: GmailSessionDetails, Object, dynamic
Can be cast to: N/A

Properties

ServerDetails

The ServerDetails are used to configure the Host and Port of the mail server to connect to and whether or not to UseSsl.

Data Type ServerDetails
Is Advanced false
Default Editor Literal
Default Value ServerDetails with value shown below:
{ 
    "Host": "",
    "Port": 465,
    "UseSsl": true
}

Credentials

The Credentials are used to configure the information required for authentication with the mail server. There are multiple data types that can be used:

Data Type IEmailCredentials
Is Advanced false
Default Editor Literal
Default Value UserCredentials with value shown below:
{ 
    "Domain": "",
    "Username": "",
    "Password": ""
}

Remarks

Create a GmailSessionDetails

The following table shows some of the ways that GmailSessionDetails can be created.

Method Example Result Editor Support Notes
Use a GmailSessionDetails constructor new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new UserCredentials("sender@gmail.com", "encryptedPassword")) {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}} Expression The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting up an app password for a Gmail account.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.
new GmailSessionDetails(serverDetails: new ServerDetails("smtp.gmail.com", 465, true), credentials: new GmailOAuthCertificateCredentials(@"C:\certificate.p12", "encryptedPassword", "sender@gmail.com", "clientId") {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"CertificatePath": "C:\\certificate.p12", "CertificatePassword": "encryptedPassword", "FromAddress": "sender@gmail.com", "ClientId": "clientId"}} Expression The CertificatePath in the GmailOAuthCertificateCredentials is a path pointing to a certificate accessible from the server executing the flow.

For information on:The CertificatePassword property must be encrypted, for more information on how to encrypt the password, see EncryptedText.

A GmailSessionDetails with a UserCredentials as the Credentials can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
ServerDetails ServerDetails Host: "smtp.gmail.com"
Port: 465
UseSsl: true
The ServerDetails that are used to connect to the server.
Credentials UserCredentials Domain: ""
Username: "sender@gmail.com"
Password: "encryptedPassword"
The Credentials that are used for authentication on the server.

The Password property in the UserCredentials can be the password associated with the username (if the account is associated with a Google Workspace with access enabled for less secure apps) or an app password, for more information, see Setting up an app password for a Gmail account.

The Password property must be encrypted, for more information on how to encrypt the password, see EncryptedText.

A GmailSessionDetails with a GmailOAuthCertificateCredentials as the Credentials can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
ServerDetails ServerDetails Host: "smtp.gmail.com"
Port: 465
UseSsl: true
The ServerDetails that are used to connect to the server.
Credentials GmailOAuthCertificateCredentials CertificatePath: $@"C:\certificate.p12"
CertificatePassword: "encryptedPassword"
FromAddress: "sender@gmail.com"
ClientId: "clientId"
The Credentials that are used for authentication on the server.

The CertificatePath in the GmailOAuthCertificateCredentials is a path pointing to a certificate which must be accessible from the server executing the flow.

For information on:The CertificatePassword property must be encrypted, for more information on how to encrypt the password, see EncryptedText.

Convert GmailSessionDetails to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"ServerDetails": {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true}, "Credentials": {"Domain": null, "Username": "sender@gmail.com", "Password": "encryptedPassword"}} "{\r\n \"ServerDetails\": {\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n },\r\n \"Credentials\": {\r\n \"Domain\": null,\r\n \"Username\": \"sender@gmail.com\",\r\n \"Password\": \"encryptedPassword\"\r\n }\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is GmailSessionDetails.
  • The Literal Editor is available for Input properties where the data type is GmailSessionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is GmailSessionDetails.

Known Limitations

None

See Also

External Documentation

None

6.4.12 - Http

Data types used for working with HTTP.

6.4.12.1 - Authentication

Data types used for authentication when working with HTTP.

6.4.12.1.1 - HttpCredentials

Used to represent details required for authentication when working with HTTP.

HttpCredentials

(Cortex.DataTypes.Http.Authentication.HttpCredentials)

6.4.12.1.2 - HttpUserCredentials

Used to represent details required for basic authentication when working with HTTP.

HttpUserCredentials

(Cortex.DataTypes.Http.Authentication.HttpUserCredentials)

6.4.12.1.3 - IHttpCredentials

Any data type used to represent details required for authentication when working with HTTP.

IHttpCredentials

(Cortex.DataTypes.Http.Authentication.IHttpCredentials)

6.4.12.1.4 - OAuth

Data types used for authentication via OAuth when working with HTTP.

6.4.12.1.4.1 - ClientAuthentication

Used to represent client credentials for OAuth.

ClientAuthentication

(Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthentication)

Summary

Properties

ClientId

ClientSecret

SendAs

6.4.12.1.4.2 - ClientAuthType

Used to represent the client authentication type for OAuth.

ClientAuthType

(Cortex.DataTypes.Http.Authentication.OAuth.ClientAuthType)

6.4.12.1.4.3 - HttpOAuthCientCredentials

Used to represent details required for OAuth authentication using client credentials.

HttpOAuthCientCredentials

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthCientCredentials)

Summary

Properties

AccessTokenUri

ClientAuthentication

Scope

6.4.12.1.4.4 - HttpOAuthCredentials

Used to represent details required for OAuth authentication.

HttpOAuthCredentials

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthCredentials)

6.4.12.1.4.5 - HttpOAuthPasswordCredentials

Used to represent details required for OAuth authentication using password credentials.

HttpOAuthPasswordCredentials

(Cortex.DataTypes.Http.Authentication.OAuth.HttpOAuthPasswordCredentials)

Summary

Properties

ResourceOwnerUsername

ResourceOwnerPassword

AccessTokenUri

ClientAuthentication

Scope

6.4.12.2 - HttpRequestVersion

Used to represent the version of HTTP to be used when making a HTTP request.

HttpRequestVersion

(Cortex.DataTypes.Http.HttpRequestVersion)

Summary

Values

HTTP10

HTTP11

6.4.12.3 - Request

Used to represent a request.

Request

(Cortex.DataTypes.Http.Request)

6.4.12.4 - RequestContentType

Used to represent the content type of a request.

RequestContentType

(Cortex.DataTypes.Http.RequestContentType)

6.4.12.5 - RequestVerb

Used to represent the type of request.

RequestVerb

(Cortex.DataTypes.Http.RequestVerb)

Summary

Values

GET

POST

PUT

DELETE

PATCH

6.4.12.6 - Rest

Data types used when working with REST.

6.4.12.6.1 - HttpRequest

Used to represent an HTTP request.

HttpRequest

(Cortex.DataTypes.Http.Rest.HttpRequest)

Summary

Properties

Uri

QueryParameters

Verb

ContentType

Headers

Body

HttpVersion

6.4.12.6.2 - HttpResponse

Used to represent an HTTP response.

HttpResponse

(Cortex.DataTypes.Http.Rest.HttpResponse)

Summary

Properties

ResponseBody

ErrorMessage

Headers

StatusCode

6.4.12.7 - Soap

Data types used when working with SOAP.

6.4.12.7.1 - Soap11Message

Used to represent a SOAP 1.1 message.

Soap11Message

(Cortex.DataTypes.Http.Soap.Soap11Message)

Summary

Properties

Action

6.4.12.7.2 - Soap12Message

Used to represent a SOAP 1.2 message.

Soap12Message

(Cortex.DataTypes.Http.Soap.Soap12Message)

Summary

Properties

6.4.12.7.3 - SoapMessage

Used to represent a SOAP message.

SoapMessage

(Cortex.DataTypes.Http.Soap.SoapMessage)

Summary

Properties

Envelope

Version

6.4.12.7.4 - SoapRequest

Used to represent a SOAP request.

SoapRequest

(Cortex.DataTypes.Http.Soap.SoapRequest)

Summary

Properties

SoapMessage

Uri

Headers

HttpVersion

6.4.12.7.5 - SoapResponse

Used to represent a SOAP response.

SoapResponse

(Cortex.DataTypes.Http.Soap.SoapResponse)

Summary

Properties

ResponseEnvelope

ErrorMessage

Headers

StatusCode

6.4.13 - Json

Data types used for working with Json.

6.4.13.1 - JsonSerializerSettings

Used to specify settings for converting objects to and from Json.

JsonSerializerSettings

(Newtonsoft.Json.JsonSerializerSettings)

Summary

Remarks

Create a JsonSerializerSettings

Convert JsonSerializerSettings to Text

Property Editor Support

Known Limitations

See Also

External Documentation

TODO:

  • Need to have a link to default settings and explain that convert object to json sets formatting.indented

6.4.14 - Logs

Data types used for working with logs.

6.4.14.1 - EventSeverity

Used to represent the severity of an event when it is logged.

EventSeverity

(Cortex.DataTypes.Logs.EventSeverity)

Summary

Values

Verbose

Debug

Information

Warning

Error

Fatal

Remarks

Create an EventSeverity

Convert EventSeverity to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.15 - Loops

Data types used for working with loops.

6.4.15.1 - InfiniteLoopErrorCode

Used to represent an error code explaining the reason an InfiniteLoopException occurred.

InfiniteLoopErrorCode

(Cortex.DataTypes.Loops.InfiniteLoopErrorCode)

Summary

Values

IncrementIsZero

IncrementIsNegative

IncrementIsPositive

Remarks

Create an InfiniteLoopErrorCode

Convert InfiniteLoopErrorCode to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.16 - Microsoft 365

Data types used for working with Microsoft 365 blocks.

6.4.16.1 - Authentication

Data types used for authentication when working with Microsoft 365 blocks.

6.4.16.1.1 - OAuth

Data types used for authentication via OAuth when working with Microsoft 365 blocks.

6.4.16.1.1.1 - Microsoft365Credentials

Used to represent details required to authenticate with Microsoft 365.

Microsoft365Credentials

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365Credentials)

6.4.16.1.1.2 - Microsoft365OAuthCertificateCredentials

Used to represent configuration for authentication via OAuth using a certificate when establishing a connection with a mail server hosted by Outlook.

Microsoft365OAuthCertificateCredentials

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCertificateCredentials)

Summary

Properties

CertificatePath

CertificatePassword

ClientId

TenantId

ObjectId

6.4.16.1.1.3 - Microsoft365OAuthCredentials

Used to represent configuration for authentication via OAuth when establishing a connection with a mail server hosted by Outlook.

Microsoft365OAuthCredentials

(Cortex.DataTypes.Microsoft365.Authentication.OAuth.Microsoft365OAuthCredentials)

Summary

Properties

ClientId

ClientSecret

TenantId

ObjectId

6.4.17 - Numbers

Data types used for working with numbers.

6.4.17.1 - Double

Used to represent a fractional, or very large or small number from -1.79769313486232e+308 through 1.79769313486232e+308.

Double

(System.Double)

Summary

The Double data type is used to represent a fractional, or very large or small number from -1.79769313486232e+308 through 1.79769313486232e+308.

Category: Numbers
Name: Double
Full Name: System.Double
Alias: double
Description: A fractional, or very large or small number from -1.79769313486232e+308 through 1.79769313486232e+308
Size: 8 bytes
Default Value: 0
Can be used as: Object, dynamic
Can be cast to: Int16, as long as value is from -32,768 through 32,767 (e.g. (Int16)32767 or (System.Int16)32767 or (short)32767)
Int32, as long as value is from -2,147,483,648 through 2,147,483,647 (e.g. (Int32)2147483647 or (System.Int32)2147483647 or (int)2147483647)
Int64, as long as value is from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807 (e.g. (Int64)9223372036854775807 or (System.Int64)9223372036854775807 or (long)9223372036854775807)
Single, as long as value is from -3.402823e+38 through 3.402823e+38 (e.g. (Single)3.402823e+38 or (System.Single)3.402823e+38 or (float)3.402823e+38)

Remarks

Create a Double

The following table shows some of the ways that a Double can be created.

Method Example Result Editor Support Notes
Declare a Double literal 0.0 0.0 Literal, Expression Zero
1.0 1.0 Literal, Expression Positive
-1.0 -1.0 Literal, Expression Negative
Use a Double expression 1.0 + 1.0 2.0 Expression Add
1.0 - 1.0 0.0 Expression Subtract
1.0 * 1.0 1.0 Expression Multiply
1.0 / 1.0 1.0 Expression Divide
Double.MaxValue 1.79769313486232e+308 Expression Maximum value of a Double. See Double.MaxValue
Double.MinValue -1.79769313486232e+308 Expression Minimum value of a Double. See Double.MinValue
Double.Parse("1") 1.0 Expression Attempts to parse text and convert it to a Double value. See Double.Parse
Convert.ToDouble("1") 1.0 Expression Attempts to convert text to a Double value. See Convert.ToDouble

Convert Double to Text

The following table shows some of the ways that a Double can be converted to text.

Method Example Result Editor Support Notes
Use ToString 1.0.ToString() "1" Expression See Double.ToString
($)DoubleVariable.ToString() where ($)DoubleVariable has a Double value of 1.0 "1" Expression See Double.ToString
Use Convert.ToString Convert.ToString(1.0) "1" Expression See Convert.ToString
Convert.ToString(($)DoubleVariable) where ($)DoubleVariable has a Double value of 1.0 "1" Expression See Convert.ToString
Use Convert Object To Text block where Object property has a Double value of 1.0 "1" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a Double value of 1.0 "1.0" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Double.
  • The Literal Editor is available for Input properties where the data type is Double.
    • Expression syntax is not supported within the Literal Editor for the Double data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Double.

Known Limitations

None

See Also

External Documentation

6.4.17.2 - Int16

Used to represent a whole number from -32,768 through 32767.

Int16

(System.Int16)

Summary

The Int16 data type is used to represent a whole number from -32,768 through 32,767.

Category: Numbers
Name: Int16
Full Name: System.Int16
Alias: short
Description: A whole number from -32,768 through 32,767
Size: 2 bytes
Default Value: 0
Can be used as: Int16, Int32, Int64, Single, Double, Object, dynamic
Can be cast to: N/A

Remarks

Create an Int16

The following table shows some of the ways that an Int16 can be created.

Method Example Result Editor Support Notes
Use an Int16 expression (Int16)(1 + 1) 2 Expression Add
(System.Int16)(1 - 1) 0 Expression Subtract
(short)(1 * 1) 1 Expression Multiply
(short)(1 / 1) 1 Expression Divide
Int16.MaxValue 32767 Expression Maximum value of an Int16. See Int16.MaxValue
Int16.MinValue -32768 Expression Minimum value of an Int16. See Int16.MinValue
Int16.Parse("1") 1 Expression Attempts to parse text and convert it to an Int16 value. See Int16.Parse
Convert.ToInt16("1") 1 Expression Attempts to convert text to an Int16 value. See Convert.ToInt16

Convert Int16 to Text

The following table shows some of the ways that an Int16 can be converted to text.

Method Example Result Editor Support Notes
Use ToString ((Int16)1).ToString() "1" Expression See Int16.ToString
($)Int16Variable.ToString() where ($)Int16Variable has an Int16 value of 1 "1" Expression See Int16.ToString
Use Convert.ToString Convert.ToString((Int16)1) "1" Expression See Convert.ToString
Convert.ToString(($)Int16Variable) where ($)Int16Variable has an Int16 value of 1 "1" Expression See Convert.ToString
Use Convert Object To Text block where Object property has an Int16 value of 1 "1" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has an Int16 value of 1 "1" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Int16.
  • The Literal Editor is available for Input properties where the data type is Int16.
    • Expression syntax is not supported within the Literal Editor for the Int16 data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Int16.

Known Limitations

None

See Also

External Documentation

6.4.17.3 - Int32

Used to represent a whole number from -2,147,483,648 through 2,147,483,647.

Int32

(System.Int32)

Summary

The Int32 data type is used to represent a whole number from -2,147,483,648 through 2,147,483,647.

Category: Numbers
Name: Int32
Full Name: System.Int32
Alias: int
Description: A whole number from -2,147,483,648 through 2,147,483,647
Size: 4 bytes
Default Value: 0
Can be used as: Int32, Int64, Single, Double, Object, dynamic
Can be cast to: Int16, as long as value is from -32,768 through 32,767 (e.g. (Int16)32767 or (System.Int16)32767 or (short)32767)

Remarks

Create an Int32

The following table shows some of the ways that an Int32 can be created.

Method Example Result Editor Support Notes
Declare an Int32 literal 0 0 Literal, Expression Zero
1 1 Literal, Expression Positive
-1 -1 Literal, Expression Negative
Use an Int32 expression 1 + 1 2 Expression Add
1 - 1 0 Expression Subtract
1 * 1 1 Expression Multiply
1 / 1 1 Expression Divide
Int32.MaxValue 2147483647 Expression Maximum value of an Int32. See Int32.MaxValue
Int32.MinValue -2147483648 Expression Minimum value of an Int32. See Int32.MinValue
Int32.Parse("1") 1 Expression Attempts to parse text and convert it to an Int32 value. See Int32.Parse
Convert.ToInt32("1") 1 Expression Attempts to convert text to an Int32 value. See Convert.ToInt32

Please see Instantiating an Int32 Value for further information.

Convert Int32 to Text

The following table shows some of the ways that an Int32 can be converted to text.

Method Example Result Editor Support Notes
Use ToString 1.ToString() "1" Expression See Int32.ToString
($)Int32Variable.ToString() where ($)Int32Variable has a value of 1 "1" Expression See Int32.ToString
Use Convert.ToString Convert.ToString(1) "1" Expression See Convert.ToString
Convert.ToString(($)Int32Variable) where ($)Int32Variable has a value of 1 "1" Expression See Convert.ToString
Use Convert Object To Text block where Object property has a value of 1 "1" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a value of 1 "1" N/A See Convert Object To Json

Please see Representing an Int32 as a String for further information.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Int32.
  • The Literal Editor is available for Input properties where the data type is Int32.
    • Expression syntax is not supported within the Literal Editor for the Int32 data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Int32.

Known Limitations

None

See Also

External Documentation

6.4.17.4 - Int64

Used to represent a whole number from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807.

Int64

(System.Int64)

Summary

The Int64 data type is used to represent a whole number from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807.

Category: Numbers
Name: Int64
Full Name: System.Int64
Alias: long
Description: A whole number from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807
Size: 8 bytes
Default Value: 0
Can be used as: Int64, Single, Double, Object, dynamic
Can be cast to: Int16, as long as value is from -32,768 through 32,767 (e.g. (Int16)32767 or (System.Int16)32767 or (short)32767)
Int32, as long as value is from -2,147,483,648 through 2,147,483,647 (e.g. (Int32)2147483647 or (System.Int32)2147483647 or (int)2147483647)

Remarks

Create an Int64

The following table shows some of the ways that an Int64 can be created.

Method Example Result Editor Support Notes
Declare an Int64 literal 9223372036854775807 9223372036854775807 Literal, Expression Positive, where value is greater than 2,147,483,647. If it is between 0 and 2,147,483,647 it will only be an Int64 if the property’s data type is also Int64, otherwise it will be an Int32.
-9223372036854775808 -9223372036854775808 Literal, Expression Negative, where value is less than -2,147,483,648. If it is between -2,147,483,648 and 0 it will only be an Int64 if the property’s data type is also Int64, otherwise it will be an Int32.
Use an Int64 expression (Int64)(1 + 1) 2 Expression Add
(System.Int64)(1 - 1) 0 Expression Subtract
(long)(1 * 1) 1 Expression Multiply
(long)(1 / 1) 1 Expression Divide
Int64.MaxValue 9223372036854775807 Expression Maximum value of an Int64. See Int64.MaxValue
Int64.MinValue -9223372036854775808 Expression Minimum value of an Int64. See Int64.MinValue
Int64.Parse("1") 1 Expression Attempts to parse text and convert it to an Int64 value. See Int64.Parse
Convert.ToInt64("1") 1 Expression Attempts to convert text to an Int64 value. See Convert.ToInt64

Please see Instantiating an Int64 Value for further information.

Convert Int64 to Text

The following table shows some of the ways that an Int64 can be converted to text.

Method Example Result Editor Support Notes
Use ToString ((Int64)1).ToString() "1" Expression See Int64.ToString
($)Int64Variable.ToString() where ($)Int64Variable has an Int64 value of 1 "1" Expression See Int64.ToString
Use Convert.ToString Convert.ToString((Int64)1) "1" Expression See Convert.ToString
Convert.ToString(($)Int64Variable) where ($)Int64Variable has an Int64 value of 1 "1" Expression See Convert.ToString
Use Convert Object To Text block where Object property has an Int64 value of 1 "1" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has an Int64 value of 1 "1" N/A See Convert Object To Json

Please see Representing an Int64 as a String for further information.

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Int64.
  • The Literal Editor is available for Input properties where the data type is Int64.
    • Expression syntax is not supported within the Literal Editor for the Int64 data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Int64.

Known Limitations

None

See Also

External Documentation

6.4.17.5 - Single

Used to represent a fractional, or very large or small number from -3.402823e+38 through 3.402823e+38.

Single

(System.Single)

Summary

The Single data type is used to represent a fractional, or very large or small number from -3.402823e+38 through 3.402823e+38.

Category: Numbers
Name: Single
Full Name: System.Single
Alias: float
Description: A fractional, or very large or small number from -3.402823e+38 through 3.402823e+38
Size: 4 bytes
Default Value: 0
Can be used as: Double, Object, dynamic
Can be cast to: Int16, as long as value is from -32,768 through 32,767 (e.g. (Int16)32767 or (System.Int16)32767 or (short)32767)
Int32, as long as value is from -2,147,483,648 through 2,147,483,647 (e.g. (Int32)2147483647 or (System.Int32)2147483647 or (int)2147483647)
Int64, as long as value is from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807 (e.g. (Int64)9223372036854775807 or (System.Int64)9223372036854775807 or (long)9223372036854775807)

Remarks

Create a Single

The following table shows some of the ways that a Single can be created.

Method Example Result Editor Support Notes
Use a Single expression 1.0f + 1.0f 2.0 Expression Add
1.0f - 1.0f 0.0 Expression Subtract
1.0f * 1.0f 1.0 Expression Multiply
1.0f / 1.0f 1.0 Expression Divide
Single.MaxValue 3.402823e+38 Expression Maximum value of a Single. See Single.MaxValue
Single.MinValue -3.402823e+38 Expression Minimum value of a Single. See Single.MinValue
Single.Parse("1") 1.0 Expression Attempts to parse text and convert it to a Single value. See Single.Parse
Convert.ToSingle("1") 1.0 Expression Attempts to convert text to a Single value. See Convert.ToSingle

Convert Single to Text

The following table shows some of the ways that a Single can be converted to text.

Method Example Result Editor Support Notes
Use ToString 1.0f.ToString() "1" Expression See Single.ToString
($)SingleVariable.ToString() where ($)SingleVariable has a Single value of 1.0 "1" Expression See Single.ToString
Use Convert.ToString Convert.ToString(1.0f) "1" Expression See Convert.ToString
Convert.ToString(($)SingleVariable) where ($)SingleVariable has a Single value of 1.0 "1" Expression See Convert.ToString
Use Convert Object To Text block where Object property has a Single value of 1.0 "1" N/A See Convert Object To Text
Use Convert Object To Json block where Object property has a Single value of 1.0 "1.0" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Single.
  • The Literal Editor is available for Input properties where the data type is Single.
    • Expression syntax is not supported within the Literal Editor for the Single data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is Single.

Known Limitations

None

See Also

External Documentation

6.4.18 - PowerShell

Data types used for working with PowerShell.

6.4.18.1 - PowerShellSessionDetails

Any data type representing configuration for executing powershell scripts on a specified host.

PowerShellSessionDetails

(Cortex.DataTypes.PowerShell.PowerShellSessionDetails)

Summary

Any data type representing configuration for executing powershell scripts on a specified host.

Category: Data
Name: PowerShellSessionDetails
Full Name: Cortex.DataTypes.PowerShell.PowerShellSessionDetails
Alias: N/A
Description: Any data type representing configuration for executing powershell scripts on a specified host.
Default Value: null
Can be used as: Object, dynamic
Can be cast to: N/A

Properties

ServerDetails

The ServerDetails are used to configure the Host and Port to connect to and whether or not to UseSsl.

Data Type ServerDetails
Is Advanced false
Default Editor Literal
Default Value ServerDetails with value shown below:
{ 
    "Host": "localhost",
    "Port": 5986,
    "UseSsl": true
}

Credentials

The Credentials are used to configure the Domain, Username and Password used to connect to the host.

Data Type UserCredentials
Is Advanced false
Default Editor Literal
Default Value UserCredentials with value shown below:
{ 
    "Domain": "",
    "Username": "",
    "Password": ""
}

PsConfiguration

The PsConfiguration controls the PowerShell configuration that will be used by the host.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value "Microsoft.PowerShell":

Remarks

Create a PowerShellSessionDetails

TODO

Convert PowerShellSessionDetails to Text

TODO

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is PowerShellSessionDetails.
  • The Literal Editor is available for Input properties where the data type is PowerShellSessionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is PowerShellSessionDetails.

Known limitations

None

See Also

None

External Documentation

None

6.4.18.2 - PowerShellWinRmSessionDetails

The data type representing configuration for executing powershell scripts on a specified host, via WinRm.

PowerShellWinRmSessionDetails

(Cortex.DataTypes.PowerShell.PowerShellWinRmSessionDetails)

Summary

The data type representing configuration for executing powershell scripts on a specified host, via WinRm.

Category: Data
Name: PowerShellWinRmSessionDetails
Full Name: Cortex.DataTypes.PowerShell.PowerShellWinRmSessionDetails
Alias: N/A
Description: The data type representing configuration for executing powershell scripts on a specified host, via WinRm.
Default Value: null
Can be used as: PowerShellSessionDetails, Object, dynamic
Can be cast to: N/A

Properties

ServerDetails

The ServerDetails are used to configure the Host and Port to connect to and whether or not to UseSsl.

Data Type ServerDetails
Is Advanced false
Default Editor Literal
Default Value ServerDetails with value shown below:
{ 
    "Host": "",
    "Port": 465,
    "UseSsl": true
}

Credentials

The Credentials are used to configure the Domain, Username and Password used to connect to the host.

Data Type UserCredentials
Is Advanced false
Default Editor Literal
Default Value UserCredentials with value shown below:
{ 
    "Domain": "",
    "Username": "",
    "Password": ""
}

PsConfiguration

The PsConfiguration controls the PowerShell configuration that will be used by the host.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value "Microsoft.PowerShell":

Remarks

Most Common PowerShellWinRmSessionDetails Data Types

Any of the following data types can be used where a PowerShellWinRmSessionDetails is required:

  • [PowerShellWinRmSessionDetails][]

Create a PowerShellWinRmSessionDetails

For some of the ways that a PowerShellWinRmSessionDetails can be created, please see each of the PowerShellWinRmSessionDetails data types:

  • [PowerShellWinRmSessionDetails][]

Convert PowerShellWinRmSessionDetails to Text

For some of the ways that a PowerShellWinRmSessionDetails can be converted to text, please see each of the PowerShellWinRmSessionDetails data types:

  • [PowerShellWinRmSessionDetails][]

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is PowerShellWinRmSessionDetails.
  • The Literal Editor is available for Input properties where the data type is PowerShellWinRmSessionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is PowerShellWinRmSessionDetails.

Known limitations

None

See Also

None

External Documentation

None

6.4.18.3 - Records

TODO.

Records

(Cortex.DataTypes.PowerShell.Records)

Summary

The Records data type is used to represent TODO.

Category: PowerShell
Name: Records
Full Name: Cortex.DataTypes.PowerShell.Records
Alias: N/A
Description: TODO.
Default Value: null
Can be used as: TODO, Object, dynamic
Can be cast to: N/A

Properties

ErrorRecords

Represents the non-terminating errors that occur from running commands or scripts during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

WarningRecords

Represents the warning messages that occur from running commands or scripts during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

DebugRecords

Represents the debug messages that occur from running commands or scripts during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

ProgressRecords

Represents the status of a running command or script that occurs during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

VerboseRecords

Represents more in depth information about the running of commands or scripts that occurs during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

InformationRecords

Represents informational context destined for the host or user that occurs during PowerShell’s execution.

Data Type IList<String>
Is Advanced false
Default Editor Expression
Default Value IList<String> with no value

Exceptions

TODO

Remarks

Create a Records

The following table shows some of the ways that Records can be created.

Method Example Result Editor Support Notes
Use a Records constructor Expression

A Records can also be created using the Literal Editor by filling in the necessary values for the following properties:

TODO:

Property Data Type Example Notes

Convert Records to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is Records.
  • The Literal Editor is available for Input properties where the data type is Records.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is Records.

Known Limitations

None

See Also

None

TODO

External Documentation

None

6.4.19 - Session Details

Data types used for working with sessions.

6.4.19.1 - ServerDetails

Used to represent details required to connect to a server.

ServerDetails

(Cortex.DataTypes.SessionDetails.ServerDetails)

Summary

The ServerDetails data type is used to represent details required to connect to a server.

Category: Session Details
Name: ServerDetails
Full Name: Cortex.DataTypes.SessionDetails.ServerDetails
Alias: N/A
Description: Details required to connect to a server.
Default Value: null
Can be used as: ServerDetails, Object, dynamic
Can be cast to: N/A

Properties

Host

The Host is used to define the address of the server to connect to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

A server address can typically be represented in one of the following formats:

  • Fully Qualified Domain Name (e.g. "smtp.gmail.com")
  • Machine name (e.g. "mail-server1")
  • IP address (e.g. "127.0.0.1")
  • Localhost (e.g. "localhost")

The server address formats supported are dependent on the block being used:

Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value ""

Port

The Port is used to define the port on the server to connect to.

Data Type Int32
Is Advanced false
Default Editor Literal
Default Value Int32 with value 0

UseSsl

UseSsl is used to define whether or not connection to the server should use SSL.

The value of this property depends on the Port for the following blocks:

Data Type Boolean
Is Advanced false
Default Editor Literal
Default Value Boolean with value true

Remarks

Create a ServerDetails

The following table shows some of the ways that ServerDetails can be created.

Method Example Result Editor Support Notes
Use a ServerDetails constructor new ServerDetails(host: "smtp.gmail.com", port: 465, useSsl: true) {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true} Expression

A ServerDetails can also be created using the Literal Editor by filling in the necessary values for the following properties:

Property Data Type Example Notes
Host EncryptableText "smtp.gmail.com" Host defines the address of the server to connect to.
Port Int32 465 Port defines the port on the server to connect to.
UseSsl Boolean true UseSsl defines whether or not connection to the server should use SSL.

Convert ServerDetails to Text

Method Example Result Editor Support Notes
Use Convert Object To Json block where Object property has a value of {"Host": "smtp.gmail.com", "Port": 465, "UseSsl": true} "{\r\n \"Host\": \"smtp.gmail.com\",\r\n \"Port\": 465,\r\n \"UseSsl\": true\r\n}" N/A See Convert Object To Json

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is ServerDetails.
  • The Literal Editor is available for Input properties where the data type is ServerDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is ServerDetails.

Known Limitations

None

See Also

External Documentation

None

6.4.20 - Ssh

Data types used for working with SSH.

6.4.20.1 - Authentication

Data types used for authenticating with servers.

6.4.20.1.1 - ISshCredentials

Used to represent details required to authenticate with a server.

ISshCredentials

(Cortex.DataTypes.Ssh.Authentication.ISshCredentials)

6.4.20.1.2 - SshCertificateCredentials

Used to represent details required to authenticate with a server, using public key credentials.

SshCertificateCredentials

(Cortex.DataTypes.Ssh.Authentication.SshCertificateCredentials)

6.4.20.1.3 - SshCredentials

Used to represent details required to authenticate with a server.

SshCredentials

(Cortex.DataTypes.Ssh.Authentication.SshCredentials)

6.4.20.1.4 - SshUserCredentials

Used to represent details required to authenticate with a server.

SshUserCredentials

(Cortex.DataTypes.Ssh.Authentication.SshUserCredentials)

6.4.20.2 - SshLogs

Used to represent logs returned by an Ssh Command.

SshLogs

(Cortex.DataTypes.Ssh.SshLogs)

6.4.20.3 - SshSessionDetails

The data type representing configuration for executing ssh commands on a specified host.

SshSessionDetails

(Cortex.DataTypes.Ssh.SshSessionDetails)

Summary

The data type representing configuration for executing ssh commands on a specified host.

Category: Data
Name: SshSessionDetails
Full Name: Cortex.DataTypes.PowerShell.SshSessionDetails
Alias: N/A
Description: The data type representing configuration for executing ssh commands on a specified host.
Default Value: null
Can be used as: PowerShellSessionDetails, Object, dynamic
Can be cast to: N/A

Properties

Host

The Host is used to define the address of the server to connect to. The value of this property may optionally be encrypted; for more information on how to encrypt this property, see EncryptableText.

A server address can typically be represented in one of the following formats:

  • Fully Qualified Domain Name (e.g. "machine.domain.com")
  • Machine name (e.g. "server1")
  • IP address (e.g. "127.0.0.1")
  • Localhost (e.g. "localhost")
Data Type EncryptableText
Is Advanced false
Default Editor Expression
Default Value EncryptableText with value ""

Port

The Port is used to define the port on the server to connect to.

Data Type Int32
Is Advanced false
Default Editor Literal
Default Value Int32 with value 22

Credentials

The Credentials are used to configure the Domain, Username and Password used to connect to the host.

Data Type ISshCredentials
Is Advanced false
Default Editor Literal
Default Value SshCertificateCredentials with value shown below:
{ 
    "Domain": "",
    "Username": "",
    "CertificatePath": "",
    "CertificatePassword": ""
}

TerminalPrompt

The regex used to match the host’s terminal prompt.

Data Type String
Is Advanced false
Default Editor Literal
Default Value String with value `"(.(~(.[\r\n]?)$

Remarks

Create a SshSessionDetails

TODO

Convert SshSessionDetails to Text

TODO

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is SshSessionDetails.
  • The Literal Editor is available for Input properties where the data type is SshSessionDetails.
  • The Variable Editor is available for Input, InputOutput and Output properties where the data type is SshSessionDetails.

Known limitations

None

See Also

TODO

None

External Documentation

None

6.4.21 - Text

Data types used for working with text.

6.4.21.1 - Char

Used to represent unicode characters.

Char

(System.Char)

Summary

The Char data type is used to represent unicode characters.

The String data type represents text as a sequence of Char values.

Category: Text
Name: Char
Full Name: System.Char
Alias: char
Description: A unicode character, surrounded by single quotes (e.g. 'a' or '!')
Size: 2 bytes
Default Value: '\0' or 'U0000'
Can be used as: Int32, Int64, Single, Double, Object, dynamic
Can be cast to: Int16 (e.g. (Int16)'a' or (System.Int16)'a' or (short)'a')

Remarks

Create a Char

The following table shows some of the ways that a Char can be created.

Method Example Result Editor Support Notes
Declare a character literal 'a' 'a' Expression
Declare a Unicode escape sequence '\u0061' 'a' Expression
Declare a hexadecimal escape sequence '\x0061' or '\x061' or '\x61' 'a' Expression
Cast an Int32 value (Char)97 'a' Expression

Property Editor Support

Currently no Input, InputOutput or Output properties require the Char data type.

Known Limitations

None

See Also

External Documentation

6.4.21.2 - CultureInfo

Used to represent information about a specific culture, including the names for the culture, the writing system, the calendar used, the sort order of strings, and formatting for dates and numbers.

CultureInfo

(System.Globalization.CultureInfo)

Summary

Remarks

Create a CultureInfo

Convert CultureInfo to Text

Property Editor Support

Known Limitations

See Also

External Documentation

TODO:

  • If the culture identifier is empty e.g (new CultureInfo("")), cultureInfo is set to InvariantCulture.
  • If the culture does not exist, the operating system will create a custom culture using the culture identifier.
  • As well as the default InvariantCulture you can also use the culture of the system (CultureInfo.CurrentCulture) or provide a new culture info (new CultureInfo(“en-GB”)).
  • Note about formatProvider and CultureInfo: If an invalid CultureInfo is provided (e.g. new CultureInfo(“enaa”)), a CultureNotFoundException will be thrown.
  • Talk about CultureInfo.InvariantCulture
  • Talk about CultureInfo.CurrentCulture

6.4.21.3 - Encoding

The data type that all encodings inherit from. An encoding is used to represent a specific character encoding (e.g. ASCII, UTF8, Unicode).

Encoding

(System.Text.Encoding)

Summary

Remarks

Create an Encoding

Convert Encoding to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.4 - EncryptableText

Used to represent text that can be, but does not need to be encrypted.

EncryptableText

(Cortex.DataTypes.Text.EncryptableText)

Summary

Remarks

Create an EncryptableText

Convert EncryptableText to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.5 - EncryptedText

Used to represent text that must be encrypted.

EncryptedText

(Cortex.DataTypes.Text.EncryptedText)

Summary

Remarks

Create an EncryptedText

Convert EncryptedText to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.6 - IFormatProvider

The data type providing the contract that all data types that control formatting must implement.

IFormatProvider

(System.IFormatProvider)

Summary

Remarks

Create a data type that implements IFormatProvider

Convert IFormatProvider to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.7 - SearchOptions

Used to define how text searches determine whether text matches the search (i.e. text contains the searched for text or matches the specified regex or pattern).

SearchOptions

(Cortex.DataTypes.Text.SearchOptions)

Summary

Values

ContainsText

Regex

PatternMatching

Remarks

Create SearchOptions

Convert SearchOptions to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.8 - String

Used to represent text.

String

(System.String)

Summary

The String data type is used to represent text.

Category: Text
Name: String
Full Name: System.String
Alias: string
Description: A sequence of unicode characters, surrounded by double quotes (e.g. "This is a string")
Size: Varies depending upon the number of characters it contains
Default Value: null
Can be used as: IEnumerable, IEnumerable<Char>, Object, dynamic
Can be cast to: N/A

Remarks

Create a String

The following table shows some of the ways that a String can be created.

Method Example Result Editor Support Notes
Declare a String literal "Hello World!" "Hello World!" Literal, Expression In the Expression Editor the surrounding double quotes (i.e. "") are needed (e.g. "Hello World!"); in the Literal Editor they are not (e.g. Hello World!). Any double quotes in the Literal Editor will be treated as literal characters that are part of the String.
Use a String expression $"Hello {($)Variable}!" where ($)Variable is set to "World!" "Hello World!" Expression Uses [String Interpolation][]
String.Format("Hello {0}!", ($)Variable) where ($)Variable is set to "World!" "Hello World!" Expression Uses String.Format
String.Concat("Hello", " ", "World!") "Hello World!" Expression Uses String.Concat
String.Join(" ", {"Hello", "World!"}) "Hello World!" Expression Uses String.Join
"Hello!".Insert(5, " World") "Hello World!" Expression Uses String.Insert
"Hello" + " " + "World!" "Hello World!" Expression Uses String Concatenation Operator (i.e. +)

Property Editor Support

  • The Expression Editor is available for Input properties where the data type is String.
  • The Literal Editor is available for Input properties where the data type is String.
    • Expression syntax is not supported within the Literal Editor for the String data type.
  • The Variable Editor is available for InputOutput and Output properties where the data type is String.

Known Limitations

None

See Also

External Documentation

6.4.21.9 - StringComparison

Used to indicate how 2 pieces of text are compared against each other (i.e. which culture to use and whether to consider case or not).

StringComparison

(System.StringComparison)

Summary

Remarks

Create a StringComparison

Convert StringComparison to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.10 - StringSplitOptions

Used to specify settings for splitting text (i.e. whether to include or remove empty entries from results).

StringSplitOptions

(System.StringSplitOptions)

Summary

Remarks

Create StringSplitOptions

Convert StringSplitOptions to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.11 - UnicodeEncoding

Used to represent Unicode character encoding.

UnicodeEncoding

(System.Text.UnicodeEncoding)

Summary

Remarks

Create a UnicodeEncoding

Convert UnicodeEncoding to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.12 - UTF32Encoding

Used to represent UTF32 character encoding.

UTF32Encoding

(System.Text.UTF32Encoding)

Summary

Remarks

Create a UTF32Encoding

Convert UTF32Encoding to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.21.13 - UTF8Encoding

Used to represent UTF8 character encoding.

UTF8Encoding

(System.Text.UTF8Encoding)

Summary

Remarks

Create a UTF8Encoding

Convert UTF8Encoding to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.22 - Other

Data types that don’t match other categories.

6.4.22.1 - Guid

Used to represent a globally unique identifier (GUID).

Guid

(System.Guid)

Summary

Remarks

Create a Guid

Convert Guid to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.22.2 - Nullable<T>

Used to represent a value type that can be set to null.

Nullable<T>

(System.Nullable<T>)

Summary

Remarks

Create a Nullable<T>

Convert Nullable<T> to Text

Property Editor Support

Known Limitations

See Also

External Documentation

6.4.23 - Most Common

Data types that are most commonly used.

Data Types

Lists

Dictionaries

InvariantCulture

HttpRequestHeaders

6.5 - Exceptions

This section includes all reference documentation for exceptions.

6.5.1 - Common

Exceptions related to commonly occurring errors

6.5.1.1 - Property

Exceptions related to issues with Block Properties

6.5.1.1.1 - PropertyContainsNullOrEmptyItemException

The exception thrown when a property is provided with a value that contains at least one item that is either null or empty, but the item is required to have a value.

PropertyContainsNullOrEmptyItemException

(Cortex.Exceptions.Common.Property.PropertyContainsNullOrEmptyItemException)

Description

The exception thrown when a property is provided with a value that contains at least one item that is either null or empty, but the item is required to have a value.

Reasons

Value Contains null or empty item

A null or empty item is contained in the value that was provided for the property.

Message Format

The format of the Message is as follows:


"'<property-name>' contains at least one null or empty value; it must only contain values that are not null or empty.
Please click the HelpLink for more information on how to fix this."

where:

  • <property-name> is the name of the property.

How to fix

Ensure the value provided for the property named <property-name> does not contain items that are either null or empty.

Properties

Exception Type

The type of the exception (i.e. PropertyContainsNullOrEmptyItemException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

For this exception:

  • <property-name> will be replaced with the name of the property.
Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

Currently, only the <property-name> has been included in the exception. In future, we will look to include the name and Id of the block, the id, name and value of the property, as well as allowing the exception to contain a link to take you directly to the offending value.

See Also

External Documentation

None

6.5.1.1.2 - PropertyEmptyException

The exception thrown when a property is provided with an empty value, but a non-empty value is required.

PropertyEmptyException

(Cortex.Exceptions.Common.Property.PropertyEmptyException)

Description

The exception thrown when a property is provided with an empty value, but a non-empty value is required.

Reasons

Empty value

An empty value was provided for the property.

Message Format

The format of the Message is as follows:

"'<property-name>' is empty; it must be provided a value.
Please click the HelpLink for more information on how to fix this."

where:

  • <property-name> is the name of the property.

How to fix

Ensure the value provided for the property named <property-name> is not empty.

Properties

Exception Type

The type of the exception (i.e. PropertyEmptyException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

For this exception:

  • <property-name> will be replaced with the name of the property.
Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

Currently, only the <property-name> has been included in the exception. In future, we will look to include the name and Id of the block, the id, name and value of the property, as well as allowing the exception to contain a link to take you directly to the offending value.

See Also

External Documentation

None

6.5.1.1.3 - PropertyItemCountException

The exception thrown when the values provided for two properties are expected to contain the same number of items, but don’t.

PropertyItemCountException

(Cortex.Exceptions.Common.Property.PropertyItemCountException)

Description

The exception thrown when the values provided for two properties are expected to contain the same number of items, but don’t.

Reasons

Item Counts Are Different

Values provided for two properties are expected to contain the same number of items, but don’t.

Message Format

The format of the Message is as follows:

"Invalid '<second-property-name>' provided.
There are <items-in-second-property> items in '<second-property-name>' and <items-in-first-property> items in '<first-property-name>'.
The number of items in '<second-property-name>' must be the same as the number of items in '<first-property-name>'.
Please click the HelpLink for more information on how to fix this."

where:

  • <first-property-name> is the name of the first property.
  • <second-property-name> is the name of the second property.
  • <items-in-first-property> is the count of items in the first property.
  • <items-in-second-property> is the count of items in the second property.

How to fix

Ensure that the value provided for each of the two properties contains the same number of items.

Properties

Exception Type

The type of the exception (i.e. PropertyItemCountException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

For this exception:

  • <first-property-name> will be replaced with the name of the first property.
  • <second-property-name> will be replaced with the name of the second property.
  • <items-in-first-property> will be replaced with the count of items in the first property.
  • <items-in-second-property> will be replaced with the count of items in the second property.
Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

Currently, the <first-property-name> and <second-property-name> have been included in the exception. In future, we will look to include the name and Id of the block, the id, name and value of the property, as well as allowing the exception to contain a link to take you directly to the offending value.

See Also

External Documentation

None

6.5.1.1.4 - PropertyNullException

The exception thrown when a property is provided with a null value, but a non-null value is required.

PropertyNullException

(Cortex.Exceptions.Common.Property.PropertyNullException)

Description

The exception thrown when a property is provided with a null value, but a non-null value is required.

Reasons

Value Is null

A null value was provided for the property when a non-null was required.

Message Format

The format of the Message is as follows:

"'<property-name>' is null; it must be provided with a non-null value.
Please click the HelpLink for more information on how to fix this."

where:

  • <property-name> is the name of the property.

How to fix

Provide a non-null value for the property.

Properties

Exception Type

The type of the exception (i.e. PropertyNullException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

For this exception:

  • <property-name> will be replaced with the name of the property.
Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

Currently, only the <property-name> has been included in the exception. In future, we will look to include the name and Id of the block, the id, name and value of the property, as well as allowing the exception to contain a link to take you directly to the offending value.

See Also

External Documentation

None

6.5.1.1.5 - PropertyValueOutOfRangeException

The exception thrown when a property is provided with a value that falls outside its accepted range.

PropertyValueOutOfRangeException

(Cortex.Exceptions.Common.Property.PropertyValueOutOfRangeException)

Description

The exception thrown when a property is provided with a value that falls outside its accepted range.

There are multiple reasons that this exception can be thrown:

Reasons

Property Is Empty

An operation such as getting, setting or removing one or more items from an empty collection property was performed.

Message Format

The format of the Message is as follows:

"Invalid '<property-name>' provided.
There are no items in '<collection-property-name>'.
Check that '<collection-property-name>' is not empty.
Please click the HelpLink for more information on how to fix this."

where:

  • <collection-property-name> is the name of the empty collection property.
  • <property-name> is the name of another property used to perform the get, set or remove operation (e.g. index, indexes, count etc.).

How to fix

Provide a non-empty collection property.

Property Is Empty Or null

An operation such as adding, getting or removing text from a null or empty (i.e. "") text property was performed.

Message Format

The format of the Message is as follows:

"Invalid '<property-name>' provided.
Check that '<property-name>' is not null or empty.
Please click the HelpLink for more information on how to fix this."

where:

  • <property-name> is the name of the null or empty (i.e. "") text property.

How to fix

Provide a non-null or non-empty text property.

Property Is Invalid

A property was set to an invalid value.

Message Format

The format of the Message can be one of the following:

"'<property-name>' given was <invalid-value>; it must be a value between <minimum-allowed-value> and <maximum-allowed-value>.
Please click the HelpLink for more information on how to fix this."

or

"'<property-name>' given was <invalid-value>; it must be a value between <minimum-allowed-value> and <maximum-allowed-value> (<calculation-of-maximum-allowed-value>).
Please click the HelpLink for more information on how to fix this."

or

"'<related-property-name>' given was <related-property-value> and '<property-name>' given was <invalid-value>.
The '<property-name>' must be less than or equal to <maximum-allowed-value> (<calculation-of-maximum-allowed-value>).
Please click the HelpLink for more information on how to fix this."

or

"Invalid '<property-name>' provided.
The values <invalid-value> in '<property-name>' are outside of the expected range.
Check that the provided values of '<property-name>' are between <minimum-allowed-value> and <maximum-allowed-value>.
Please click the HelpLink for more information on how to fix this."

where:

  • <property-name> is the name of the property with the invalid value (e.g. Length, Count, Index).
  • <invalid-value> is the invalid value of the property (e.g. 100 for non-collection values or 100, 200 for collection values).
  • <minimum-allowed-value> is the minimum value allowed (e.g. 0).
  • <maximum-allowed-value> is the maximum value allowed (e.g. 9).
  • <calculation-of-maximum-allowed-value> is how the maximum allowed value is calculated (e.g. 'Text.Length' - 1).
  • <related-property-name> is the name of a related property relevant to the exception (e.g. Index).
  • <related-property-value> is the value of a related property relevant to the exception (e.g. 1).

How to fix

Provide a valid value for the property as instructed by the Message.

Property Is Negative

A property was set to a negative TimePeriod when a positive TimePeriod was required.

Message Format

The format of the Message is as follows:

"The provided 'TimePeriod' (<time-period-value-as-text>) equates to <time-period-value-as-milliseconds> milliseconds which is invalid; it must be a non-negative value.
Please click the HelpLink for more information on how to fix this."

where:

  • <time-period-value-as-text> is the TimePeriod value in its text representation (e.g. 0.0.0.0:0:0:-10).
  • <time-period-value-as-milliseconds> is the TimePeriod value represented as total milliseconds (e.g. -10).

How to fix

Provide a valid non-negative TimePeriod value for the property as instructed by the Message.

Property Greater Than Maximum Value

A positive TimePeriod was added to the property or a negative TimePeriod was subtracted from the property, and the result is greater than the allowed maximum value of the DateTimeOffset data type.

Message Format

The format of the Message can be one of the following:

"The provided 'DateTimeOffset' (<value-of-date-time-offset-property>) with the addition of the given 'TimePeriod' (<value-of-time-period-property>) is greater than the maximum of a DateTimeOffset (<maximum-value-of-date-time-offset>).
Please click the HelpLink for more information on how to fix this."
"The provided 'DateTimeOffset' (<value-of-date-time-offset-property>) with the subtraction of the given 'TimePeriod' (<value-of-time-period-property>) is greater than the maximum of a DateTimeOffset (<maximum-value-of-date-time-offset>).
Please click the HelpLink for more information on how to fix this."

where:

  • <value-of-date-time-property> is the value of the DateTimeOffset in ISO 8601 format (i.e. 2022-07-01T14:00:00.0000000+01:00).
  • <value-of-time-period-property> is the value of the TimePeriod in text format (i.e. 9999.0.0.0:0:0:0).
  • <maximum-value-of-date-time-offset> is the maximum value of a DateTimeOffset (i.e. 9999-12-31T23:59:59.9999999+00:00).

How to fix

Provide a TimePeriod value that when added to or subtracted from the property results in the property being less than the allowed maximum value of the DateTimeOffset data type.

Property Less Than Minimum Value

A positive TimePeriod was subtracted from the property or a negative TimePeriod was added to the property, and the result was less than the allowed minimum value of the DateTimeOffset data type.

Message Format

The format of the Message can be one of the following:

"The provided 'DateTimeOffset' (<value-of-date-time-offset-property>) with the subtraction of the given 'TimePeriod' (<value-of-time-period-property>) is less than the minimum of a DateTimeOffset (<minimum-value-of-date-time-offset>).
Please click the HelpLink for more information on how to fix this."
"The provided 'DateTimeOffset' (<value-of-date-time-offset-property>) with the addition of the given 'TimePeriod' (<value-of-time-period-property>) is less than the minimum of a DateTimeOffset (<minimum-value-of-date-time-offset>).
Please click the HelpLink for more information on how to fix this."

where:

  • <value-of-date-time-property> is the value of the DateTimeOffset in ISO 8601 format (i.e. 2022-07-01T14:00:00.0000000+01:00).
  • <value-of-time-period-property> is the value of the TimePeriod in text format (i.e. -9999.0.0.0:0:0:0).
  • <minimum-value-of-date-time-offset> is the minimum value of a DateTimeOffset (i.e. 0001-01-01T00:00:00.0000000+00:00).

How to fix

Provide a TimePeriod value that when added to or subtracted from the property results in the property being greater than the allowed minimum value of the DateTimeOffset data type.

Properties

Exception Type

The type of the exception (i.e. PropertyValueOutOfRangeException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

None

See Also

External Documentation

None

6.5.1.2 - UnencryptedTextException

UnencryptedTextException

(Cortex.Exceptions.Common.UnencryptedTextException)

6.5.2 - Data

Exceptions related to Data Sources

6.5.2.1 - CommandException

Exception thrown when any command execution has resulted in an exception being thrown.

CommandException

(Cortex.Exceptions.Data.CommandException)

Exception thrown when any command execution has resulted in an exception being thrown.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

TODO: This is an example of how we can do exceptions with categories and error codes

Category Error Code Notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes

BasicCredentials.AccessTokenUri

300

How to fix

TODO:

301

How to fix

TODO:

302

How to fix

TODO:

6.5.2.2 - InvalidConnectionStringException

Exception thrown when an invalid connection string is used.

InvalidConnectionStringException

(Cortex.Exceptions.Data.InvalidConnectionStringException)

Exception thrown when an invalid connection string is used.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

TODO: This is an example of how we can do exceptions with categories and error codes

Category Error Code Notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes

BasicCredentials.AccessTokenUri

300

How to fix

TODO:

301

How to fix

TODO:

302

How to fix

TODO:

6.5.3 - Decisions

Exceptions related to Decisions

6.5.3.1 - PropertyNotNullableException

The exception thrown when a property cannot accept a non-nullable value type.

PropertyNotNullableException

(Cortex.Exceptions.Decisions.PropertyNotNullableException)

The exception thrown when a property cannot accept a non-nullable value type.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

TODO: This is an example of how we can do exceptions with categories and error codes

Category Error Code Notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes
BasicCredentials 300 Some notes
301 Some notes
302 Some notes

BasicCredentials.AccessTokenUri

300

How to fix

TODO:

301

How to fix

TODO:

302

How to fix

TODO:

6.5.4 - Dictionaries

Exceptions related to Dictionaries

6.5.4.1 - CannotModifyReadOnlyDictionaryException

The exception thrown when trying to modify a read-only dictionary.

CannotModifyReadOnlyDictionaryException

(Cortex.Exceptions.Dictionaries.CannotModifyReadOnlyDictionaryException)

The exception thrown when trying to modify a read-only dictionary.

Dictionaries implementing IDictionary<TKey, TItem> have the option to be read-only.

The format of the exception message is as follows:

"'<property-display-name>' cannot be because it's read-only.
Please click the HelpLink for more information on how to fix this."

How to fix

If the dictionary was written directly into the block property using an expression, use a dictionary type that is not read-only, such as Dictionary<TKey, TItem>.

When using a variable, convert the read-only dictionary to a dictionary that can be written to by using the .ToDictionary(item => item.Key, item => item.Value) expression like follows:

($)Dictionary.ToDictionary(item => item.Key, item => item.Value);

TODO: Confirm if this is all correct

6.5.4.2 - KeyNotPresentException

The exception thrown when trying to get an item from a dictionary, or set an item in a dictionary, with a key that is not present.

KeyNotPresentException

(Cortex.Exceptions.Dictionaries.KeyNotPresentException)

The exception thrown when trying to get an item from a dictionary, or set an item in a dictionary, with a key that is not present.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.4.3 - KeyPresentException

The exception thrown when trying to add an item to a dictionary with a key that is already present.

KeyPresentException

(Cortex.Exceptions.Dictionaries.KeyPresentException)

The exception thrown when trying to add an item to a dictionary with a key that is already present.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.4.4 - KeysNotPresentException

The exception thrown when trying to get items from a dictionary, or set items in a dictionary, and one of the keys used to find the items is not present.

KeysNotPresentException

(Cortex.Exceptions.Dictionaries.KeysNotPresentException)

The exception thrown when trying to get items from a dictionary, or set items in a dictionary, and one of the keys used to find the items is not present.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.4.5 - OccurrenceNotPresentException

The exception thrown when trying to get a specified occurrence of an item from a dictionary, or set a specified occurrence of an item in a dictionary.

OccurrenceNotPresentException

(Cortex.Exceptions.Dictionaries.OccurrenceNotPresentException)

The exception thrown when trying to get a specified occurrence of an item from a dictionary, or set a specified occurrence of an item in a dictionary.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.5 - Email

Exceptions related to Email

6.5.5.1 - EmailSessionException

The exception thrown when an issue occurs while opening a session with a mail server.

EmailSessionException

(Cortex.Exceptions.Email.EmailSessionException)

Description

The exception thrown when an issue occurs while opening a session with a mail server.

There are multiple reasons that this exception can be thrown:

Reasons

Invalid Port

A Category of Socket and an Error Code of 100 indicates that the Port provided in the ServerDetails is invalid.

Message Format

The format of the Message is as follows:

"The connection attempt to 'Host' ('<host>') on 'Port' (<port>) failed. The 'Server Details' in 'Email Session Details' has been provided a port that does not exist or the connection timed out.
Please click the HelpLink for more information on how to fix this."

where:

  • <host> is the address of the mail server that a session is being opened with
  • <port> is the port on the mail server that a session is being opened with

How to Fix

Provide a valid Port between the Int32 values 1 and 65535 in the ServerDetails and ensure that the mail server is up and running without issues.


Invalid Host

A Category of Socket and an Error Code of 101 indicates that the Host provided in the ServerDetails is invalid.

Message Format

"Invalid 'Host' ('<host>') provided. The 'Server Details' in 'Email Session Details' has been provided a host that does not exist.
Please click the HelpLink for more information on how to fix this."

where:

  • <host> is the address of the mail server that a session is being opened with

How to Fix

Provide a valid Host in the ServerDetails.


SSL Required

A Category of SSL and an Error Code of 200 indicates that SSL is required. More specifically, the mail server is expecting that SSL is used as soon as the connection is established.

Message Format

"The connection could not be established or disconnected unexpectedly. Check if the 'Port' (<port>) provided requires that 'Use SSL' be set to true.
Please click the HelpLink for more information on how to fix this."

where:

  • <port> is the port on the mail server that a session is being opened with

How to Fix

Change UseSsl in the ServerDetails to true, or make a connection on a Port which does not require SSL.


SSL Unsupported

A Category of SSL and an Error Code of 201 indicates that one of the following issues occurred:

  • An SSL connection is not supported. More specifically, the mail server either does not support SSL connections or only supports SSL connections via the STARTTLS command.
  • Certificate on the Host is expired, untrusted or invalid
  • Certificate replaced by anti-virus software in order to scan web traffic resulting in failed certificate validation
  • CRL server is down

Message Format

"The connection could not be established or disconnected unexpectedly. Check if the 'Port' (<port>) provided requires that 'Use SSL' be set to false. If this is not the case, check the inner exception.
Please click the HelpLink for more information on how to fix this."

where:

  • <port> is the port on the mail server that a session is being opened with

How to Fix

Change UseSsl in the ServerDetails to false, or make a connection on a port which supports SSL.

If the above suggestion does not fix the problem, check if the anti-virus software on the server executing the flow is replacing the SSL certificate in order to scan the web traffic, and change the settings appropriately if needed.

If the issue persists, please check the inner exception as instructed by the Message.


Invalid User Credentials

A Category of UserCredentials and an Error Code of 300 indicates that the Username and Password combination provided in the UserCredentials is invalid.

Message Format

"The provided 'Username' and 'Password' is incorrect. The 'User Credentials' in 'Email Session Details' has been provided an incorrect username and password combination.
Please click the HelpLink for more information on how to fix this."

How to Fix

Provide a valid Username and Password combination in the UserCredentials.


Invalid SSL Certificate

A Category of OAuthCredentials and an Error Code of 400 indicates that one of the following issues occurred:

Message Format

"The 'Certificate Path' ('<certificate-path>') or 'Certificate Password' is invalid. The 'Gmail OAuth Certificate Credentials' in 'Email Session Details' has been provided an incorrect certificate path or certificate password.
Please click the HelpLink for more information on how to fix this."

where:

  • <certificate-path> is the path pointing to the SSL certificate

How to Fix

Provide a CertificatePath which is a valid file path pointing to a valid SSL certificate and ensure that the CertificatePassword is correct in the GmailOAuthCertificateCredentials.


Invalid Gmail Client Credentials

A Category of OAuthCredentials and an Error Code of 401 indicates that an invalid FromAddress and ClientId combination has been provided in the GmailOAuthCertificateCredentials.

Message Format

"The 'From Address' ('<from-address>}') or 'Client Id' ('<client-id>') is invalid. The 'Gmail OAuth Certificate Credentials' in 'Email Session Details' has been provided an incorrect email address or Client ID.
Please click the HelpLink for more information on how to fix this."

where:

  • <from-address> is the email address to send the email from
  • <client-id> is the client ID for the client application

How to Fix

Provide a valid FromAddress and ensure that the ClientId is correct in the GmailOAuthCertificateCredentials.


Properties

Exception Type

The type of the exception (i.e. EmailSessionException)

Data Type String

Message

The exception message, providing information about the exception that occurred.

Data Type String

Category

The category of the exception, which is used to categorise an exception if there are multiple reasons that the exception can occur.

For EmailSessionException there are the following categories:

  • Socket
  • SSL
  • UserCredentials
  • OAuthCredentials
Data Type String

Error Code

The error code for the exception, which is used to indicate the reason that the exception occurred, if there are multiple reasons that the exception can occur.

For EmailSessionException there are the following error codes:

Data Type EmailSessionErrorCode

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

None

See Also

External Documentation

None

6.5.6 - Files & Folders

Exceptions related to Files and Folders

6.5.6.1 - InvalidFolderNameException

The exception thrown when a folder name is invalid.

InvalidFolderNameException

(Cortex.Exceptions.FilesAndFolders.InvalidFolderNameException)

The exception thrown when specifying an invalid folder name.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.6.2 - InvalidPathException

The exception thrown when a file or folder path is invalid.

InvalidPathException

(Cortex.Exceptions.FilesAndFolders.InvalidPathException)

The exception thrown when specifying an invalid file or folder path.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.6.3 - OperationFailedException

The exception thrown when a file or folder operation failed for one or more paths.

OperationFailedException

(Cortex.Exceptions.FilesAndFolders.OperationFailedException)

The exception thrown when a file or folder operation failed for one or more paths.

Path Exceptions

PathDoesNotExist

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

Blocks that can throw this exception

TODO:

PathTooLong

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

Blocks that can throw this exception

TODO:

Indexes Of Duplicate Paths

/// If any path in the specified filePaths is duplicated and no exception is thrown for that path, the block will only process the first occurrence of the path, skipping any other occurrences.

        /// If any path in the specified filePaths is duplicated and an exception occurs for that path an <see cref="OperationFailedException">OperationFailedException</see> will be thrown, and the path added to the "IndexesOfDuplicatePaths" dictionary in <see cref="OperationFailedException">OperationFailedException</see>.

Indexes Of Null Or Empty Paths

/// If any path in the specified filePaths is null or empty, an OperationFailedException will be thrown, and the path added to the “IndexesOfNullOrEmptyPaths” list in OperationFailedException.

How to fix

TODO:

6.5.7 - FlowException

The exception thrown by the ThrowNewFlowException block.

FlowException

(Cortex.Exceptions.FlowException)

The exception thrown by the ThrowNewFlowException block.

TODO:

How to fix

TODO:

6.5.8 - Flows

Exceptions related to Flows

6.5.8.1 - Blocks

Exceptions related to Blocks

6.5.8.1.1 - BlockTimeoutException

The exception thrown when a block timeout has been reached.

BlockTimeoutException

(Cortex.Exceptions.Flows.Blocks.BlockTimeoutException)

Description

TODO

Reasons

Block Timeout Reached

TODO

Message Format

TODO

The format of the Message is as follows:

"TODO: \r\nPlease click the HelpLink for more information on how to fix this."

How to fix

TODO

Ensure the action that the block is taking is likely to complete within the given TimePeriod.

Properties

TODO

Exception Type

The type of the exception (i.e. BlockTimeoutException).

Data Type String

Message

TODO

The exception message, providing information about the exception that occurred.

Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

TODO

If a block is at a point that cannot cancel, then it will cancel at the next available opportunity.

See Also

TODO

TODO

TODO

TODO: Update list

All Blocks except:

External Documentation

TODO

6.5.8.1.2 - InvalidBlockTimeoutException

The exception thrown when a block timeout is invalid.

InvalidBlockTimeoutException

(Cortex.Exceptions.Flows.Blocks.InvalidBlockTimeoutException)

Description

TODO

Reasons

Block Timeout Reached

TODO

Message Format

TODO

The format of the Message is as follows:

"TODO: \r\nPlease click the HelpLink for more information on how to fix this."

How to fix

TODO

Ensure the action that the block is taking is likely to complete within the given TimePeriod.

Properties

TODO

Exception Type

The type of the exception (i.e. InvalidBlockTimeoutException).

Data Type String

Message

TODO

The exception message, providing information about the exception that occurred.

Data Type String

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

TODO

If a block is at a point that cannot cancel, then it will cancel at the next available opportunity.

See Also

TODO

TODO

TODO

TODO: Update list

All Blocks except:

External Documentation

TODO

6.5.8.1.3 - InvalidPropertyValueException

The exception thrown when a property is provided with an invalid value.

InvalidPropertyValueException

(Cortex.Exceptions.Flows.Blocks.InvalidPropertyValueException)

Description

The exception thrown when a property is provided with an invalid value.

This exception wraps the InnerException that occurred when the value provided for the property was used.

Reasons

Value Is Invalid

An invalid value was provided for the property with the specified PropertyId.

Message Format

The format of the Message is as follows:

"The value of the property could not be evaluated."

How to fix

Provide a valid value for the property with the specified PropertyId, as instructed by the Message.

More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the message of the InnerException.

Properties

Exception Type

The type of the exception (i.e. InvalidPropertyValueException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

For this exception, the message will always be the same. More information on why the value is invalid, or instruction on how to provide a valid value, may be present in the message of the InnerException.

Data Type String

PropertyId

The Id of the property that has been provided an invalid value.

Data Type Guid

InnerException

The exception that occurred when the value provided for the property was used.

This may contain more information on why the value is invalid, or instruction on how to provide a valid value in its message.

Data Type Exception

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

Currently, only the PropertyId has been included in the exception. In future, we will look to include the name and Id of the block, the name and value of the property, as well as allowing the exception to contain a link to take you directly to the offending value.

See Also

External Documentation

None

6.5.8.2 - Execution

Exceptions related to the Execution of Flows

6.5.8.2.1 - InvalidInputVariablesException

The exception thrown when trying to run a flow with invalid input variables.

InvalidInputVariablesException

(Cortex.Exceptions.Flows.Execution.InvalidInputVariablesException)

Description

The exception thrown when trying to run a flow with invalid Input Variables.

Reasons

Missing Input Variables

This exception is thrown when a flow is run and there are missing Input Variables; any missing variables will be shown in the InvalidVariableErrors property.

Message Format

The format of the Message is as follows:

"Couldn't initialize variable store because of invalid input variables."

How to fix

Add the variables referenced in InvalidVariableErrors.

Extra Input Variables

This exception is thrown when a flow is run and extra Input Variables have been provided; any extra variables will be shown in the InvalidVariableErrors property.

Message Format

The format of the Message is as follows:

"Couldn't initialize variable store because of invalid input variables."

How to fix

Remove the variables referenced in InvalidVariableErrors.

Input Variables of an Invalid Type

This exception is thrown when a flow is run and there are Input Variables that are of an invalid type; any variables with an invalid type will be shown in the InvalidVariableErrors property.

Message Format

The format of the Message is as follows:

"Couldn't initialize variable store because of invalid input variables."

How to fix

Ensure the value provided for the variables referenced in InvalidVariableErrors is either the same type as, or can be implicitly cast to the type defined in the default value for that Input Variable.

Properties

Exception Type

The type of the exception (i.e. InvalidInputVariablesException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

Data Type String

InvalidVariableErrors

A List<InputVariableError> containing each invalid variable passed into the flow.

Data Type List<InputVariableError>

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

None

See Also

None

External Documentation

None

6.5.9 - Http

Exceptions related to HTTP

6.5.9.1 - HttpAuthorisationException

The exception thrown when an issue occurs during the authorisation process when working with HTTP.

HttpAuthorisationException

(Cortex.Exceptions.Http.HttpAuthorisationException)

6.5.9.2 - InvalidRequestException

The exception thrown when an issue occurs with a HTTP request.

InvalidRequestException

(Cortex.Exceptions.Http.InvalidRequestException)

6.5.9.3 - InvalidResponseException

The exception thrown when an issue occurs with a HTTP response.

InvalidResponseException

(Cortex.Exceptions.Http.InvalidResponseException)

6.5.10 - List

Exceptions related to Lists

6.5.10.1 - CannotModifyReadOnlyListException

The exception thrown when trying to modify a read-only list.

CannotModifyReadOnlyListException

(Cortex.Exceptions.Lists.CannotModifyReadOnlyListException)

The exception thrown when trying to modify a read-only list.

Lists deriving from IList<T> have the option to be read-only.

The format of the exception message is as follows:

"The value of '<property-display-name>' cannot be modified.
This is because the value of '<property-display-name>' is read-only.
See the CannotModifyReadOnlyListException help page for more information on how to fix this."

How to fix

If the list was written directly into the block property using an expression, use a list type that is not read-only, such as List<T>.

When using a variable, convert the list to a list that can be written to by using the .ToList() expression like follows:

($)List.ToList()

TODO: Confirm if this is all correct - look at cannotmodifyreadonlydictionaryexception for consistency

6.5.10.2 - DuplicateValueException

The exception thrown when a list contains duplicate values and shouldn’t.

DuplicateValueException

(Cortex.Exceptions.Lists.DuplicateValueException)

TODO: The exception thrown when…

The format of the exception message is as follows:

TODO: Format

How to fix

TODO: How to fix…

6.5.11 - Loops

Exceptions related to Loops.

6.5.11.1 - InfiniteLoopException

The exception thrown when an infinite loop can occur.

InfiniteLoopException

(Cortex.Exceptions.Loops.InfiniteLoopException)

Description

The exception thrown when an infinite loop can occur.

There are multiple reasons that this exception can be thrown:

Reasons

Increment Is Zero

A Category of "Increment"and an Error Code of 100 indicates that a zero increment value was provided.

Message Format

The format of the Message can be one of the following:

  • If a zero value was provided and a negative value was expected
"The 'Increment' provided (0) causes an infinite loop. It must be a negative value.
Please click the HelpLink for more information on how to fix this."
  • If a zero value was provided and a positive value was expected
"The 'Increment' provided (0) causes an infinite loop. It must be a positive value.
Please click the HelpLink for more information on how to fix this."

How to fix

Provide a negative or positive value for the increment as instructed by the Message.

Increment Is Negative

A Category of "Increment"and an Error Code of 101 indicates that a negative increment value was provided when a positive value was required.

Message Format

The format of the Message is as follows:

"The 'Increment' provided ({NegativeIncrement}) causes an infinite loop. It must be a positive value.
Please click the HelpLink for more information on how to fix this."

How to fix

Provide a positive value for the increment as instructed by the Message.

Increment Is Positive

A Category of "Increment"and an Error Code of 102 indicates that a positive increment value was provided when a negative value was required.

Message Format

The format of the Message is as follows:

"The 'Increment' provided ({PositiveIncrement}) causes an infinite loop. It must be a negative value.
Please click the HelpLink for more information on how to fix this."

How to fix

Provide a negative value for the increment as instructed by the Message.

Properties

Exception Type

The type of the exception (i.e. InfiniteLoopException).

Data Type String

Message

The exception message, providing information about the exception that occurred.

Data Type String

Category

The category of the exception, which is used to categorise an exception if there are multiple reasons that the exception can occur.

For InfiniteLoopException the only category is Increment.

Data Type String

Error Code

The error code for the exception, which is used to indicate the reason that the exception occurred, if there are multiple reasons that the exception can occur.

For InfiniteLoopException there are three error codes:

  • 100 - indicates the increment is zero, but should be either negative or positive
  • 101 - indicates the increment is negative, but should be positive
  • 102 - indicates the increment is positive, but should be negative
Data Type InfiniteLoopErrorCode

The URL for the relevant section of this exception’s help page.

Data Type String

Remarks

Known Limitations

None

See Also

External Documentation

None

6.5.12 - PowerShell

Exceptions related to PowerShell

6.5.12.1 - PSException

Exception thrown when a terminating error occurs while executing scripts over WinRM.

PSException

(Cortex.Exceptions.PowerShell.PSException)

Exception thrown when a terminating error occurs while executing scripts over WinRM.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.12.2 - PSRemotingException

Exception thrown when access is denied to a host when attempting to executing scripts over WinRM.

PSRemotingException

(Cortex.Exceptions.PowerShell.PSRemotingException)

Exception thrown when access is denied to a host when attempting to executing scripts over WinRM.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.13 - Ssh

Exceptions related to Ssh

6.5.13.1 - SshClientException

Exception thrown when an error occurs from the Sshclient object.

SshClientException

(Cortex.Exceptions.Ssh.SshClientException)

Exception thrown when an error occurs from the Sshclient object.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.13.2 - SshResponseException

Exception thrown when an error occurs from the Ssh response.

SshResponseException

(Cortex.Exceptions.Ssh.SshResponseException)

Exception thrown when an error occurs from the Ssh response.

The format of the exception message is as follows:

"TODO.
Please click the HelpLink for more information on how to fix this."

How to fix

TODO:

6.5.14 - Text

Exceptions related to Text blocks

6.5.14.1 - Regex

Exceptions related to issues with Regex

6.5.14.1.1 - RegexParsingFailedException

The exception thrown when a property is provided with an invalid regex value.

RegexParsingFailedException

(Cortex.Exceptions.Text.Regex.RegexParsingFailedException)

The exception thrown when a property is provided with an invalid regex value.

The format of the exception message is as follows:

TODO

How to fix

Provide a valid regex value for the property.

6.5.15 - Xml

Exceptions related to Xml blocks.

6.5.15.1 - XmlSerializationException

The exception thrown when an Xml Serialization errors occur.

XmlSerializationException

(Cortex.Exceptions.Xml.XmlSerializationException)

TODO: The exception thrown when…

The format of the exception message is as follows:

TODO: Format

How to fix

TODO: How to fix…

6.6 - Logs

This section includes all reference documentation for logs generated by the Cortex Innovation platform.

6.6.1 - Cortex Gateway

This section includes all reference documentation for the logs generated by Cortex Gateway.

6.6.2 - Cortex Studio

This section includes all reference documentation for the logs generated by Cortex Studio.

6.6.3 - Cortex Flow Debugger Service

This section includes all reference documentation for the logs generated by the Cortex Flow Debugger Service.

TODO:

  • Configuration
    • Serilog
    • Log Event block
  • Structure of a log
  • Different types of log
    • Pause
    • CreateDebugSession
    • etc

6.6.4 - Cortex API Gateway Service

This section includes all reference documentation for the logs generated by the Cortex API Gateway Service.

6.6.5 - Cortex Flow Execution Service

This section includes all reference documentation for the logs generated by the Cortex Flow Execution Service.

6.7 - Messages

This section includes all reference documentation for messages generated by the Cortex Innovation platform.

6.7.1 - Validation

This section includes all reference documentation for messages generated during validation.

6.7.1.1 - Errors

This section includes all reference documentation for errors generated during validation.

6.8 - Observability

This section includes all reference documentation for the Observability platform for Cortex Innovation.

6.8.1 - Grafana

This section includes all reference documentation for the Grafana Observability platform for Cortex Innovation.

6.8.1.1 - Dashboards

This section includes all reference documentation for the Cortex Innovation default set of Grafana dashboards.

6.8.1.1.1 - Flow Execution Requests

Information about the Flow Executions Request Dashboard.

Flow Execution Requests

Description

This dashboard provides the information required to analyse the flow execution requests within the Cortex Innovation platform. It will display data based on the Time Range that has been specified.

At the top of the page there is a dashboard description. This provides information about what the dashboard is reporting and what each of the filters are. The description is always collapsed by default.

The dashboard is then split into 4 main sections:

There are several filters available to filter the data to a more fine-grained level as necessary and are explained in further detail below.

Time Range

The time range for which the dashboard displays data is configurable in the top right of the dashboard using the Time Range selector (defaults to the last 3 hours):

There are a number of predefined quick ranges to choose from:

  • Last 5, 15 and 30 minutes
  • Last 1, 3, 6, 12 and 24 hours
  • Last 2, 7, 30 and 90 days
  • Last 6 months
  • Last 1, 2 and 5 years
  • Yesterday
  • Day before yesterday
  • This day last week
  • Previous week, month, fiscal quarter, year, fiscal year
  • Today
  • Today so far
  • This month, fiscal quarter, year and fiscal year
  • This month, fiscal quarter, year and fiscal year so far

To configure an absolute time range, you should specify a From and To date and time. These values can be in the format of YYYY-MM-DD HH:MM:SS, e.g. 2022-07-22 13:54:23, or alternatively can use times relative to now, e.g. now-24h. It is also possible to use the date time picker available for both the From and To fields. Once the absolute time range has been configured you must click the ‘Apply time range’ button.

If an absolute time range is specified, the Time Range selector will show the selected time range with arrows either side. These arrows can be used to shift the time range forwards and backwards. This feature is not available for quick ranges.

The magnifying glass icon allows you to zoom out of the time range specified. It will substract half the current time range from the From field and add half the current time range to the To field.

For more information regarding the Time Range selector, see Grafana’s Time range controls documentation.

Filters

At the top of the dashboard, there are 10 filters available to restrict the data queried:

Filter Description
Tenant List of tenants. Defaulted to All.
System List of systems. Defaulted to All.
Node List of hosts that processed the requests. Defaulted to All.
Package Name List of packages. Defaulted to All.
Flow Name List of flows that have execution requests. Defaulted to All.
Status Code List of status codes found in the HTTP responses. Defaulted to All.
Result List of results found in the HTTP responses. Defaulted to All.
Initiator IP Address List of IP addresses for the initiators of the requests. Defaulted to All.
Interval List of intervals to perform the time series aggregations upon. This only affects the graphs on this dashboard.

The available values for this filter are auto, 1m, 10m, 30m, 1h, 6h, 12h, 1d, 7d, 14d, 30d.

If auto is selected, as is the default, Grafana will aggregate to a level it deems appropriate for the time range specified.
Custom Filter Enables filtering on all available values, including those not exposed by default.

All filters (excluding Interval and Custom Filter) will display their list of available options dependent on the preceding filters selected.

Overview Section

This section displays key flow execution request metrics for the specified time range and consists of 4 panels.

Total Requests

This tile displays the total number of flow execution requests during the specified time range.

Total Requests Errored

This tile displays the total number of flow execution requests that errored during the specified time range. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be customised, however the default thresholds are:

Threshold Value Colour
OK 0 green
CRITICAL >= 1 red

Request Error Rate

This tile displays the percentage of errored flow execution requests against the total flow execution requests during the specified time range. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be customised, however the default thresholds are:

Threshold Value Colour
OK < 5% green
WARNING >= 5% orange
CRITICAL >= 10% red

Mean Request Duration

This tile displays the mean duration for flow execution requests during the specified time range. This is usually reported in seconds, however the unit may change if the number is much smaller or larger.

Requests Section

This section provides information regarding the flow execution request history for the specified time range and consists of 3 panels.

Requests

This graph displays, for the specified time range, the:

  • count of all flow execution requests
  • mean duration in seconds for all flow execution requests

Each data point value is calculated by aggregating requests based on the Interval filter.

Top 10 Requests by Count

This table displays the 10 flows with the most execution requests during the specified time range with their mean, minimum and maximum duration in seconds.

Bottom 10 Requests by Count

This table displays the 10 flows with the least execution requests during the specified time range with their mean, minimum and maximum duration in seconds.

Errors Section

This section provides information regarding the errored flow execution request history for the specified time range and consists of 2 panels.

Errored Requests

This graph displays, for the specified time range, the:

  • count of errored flow execution requests
  • mean duration in seconds for errored flow execution requests

Each data point value is calculated by aggregating requests based on the Interval filter.

Top 10 Requests by Error Count

This table displays the 10 flows with the most errored execution requests (by status code and result) during the specified time range with their mean, minimum and maximum duration in seconds.

Duration Section

This section provides information regarding the flow execution request duration history for the specified time range and consists of 3 panels.

Request Duration

This graph displays, for the specified time range, the:

  • mean duration in seconds for all flow execution requests
  • minimum duration in seconds for all flow execution requests
  • maximum duration in seconds for all flow execution requests

Each data point value is calculated by aggregating requests based on the Interval filter.

Top 10 Longest Running Requests by Mean Duration

This table displays the 10 flows whose execution requests have the longest mean duration during the specified time range with their total count, error count, minimum and maximum duration in seconds.

Top 10 Shortest Running Requests by Mean Duration

This table displays the 10 flows whose execution requests have the shortest mean duration during the specified time range with their total count, error count, minimum and maximum duration in seconds.

Remarks

Unknown values

The dashboard may display flow execution requests that have an Unknown status code or result, if they are missing from the raw logs. The chances of this occurring are minimal.

Known Limitations

Graphs do not reset to zero

There is a limitation in Grafana where the graph does not always return to the zero line when there is no data for a given time point. This only occurs when there is a data point available at the beginning of the graph, followed by a period with no data, then data occurs again. When hovering the mouse over this area, it will show that the value is 0, and any other tiles will reflect the zero data at this point accordingly.

None

6.8.1.1.2 - Platform Health

Information about the Platform Health Dashboard.

Platform Health

Description

This dashboard provides the information required to analyse the health of the Cortex Innovation platform. It will display data based on the Time Range that has been specified.

At the top of the page there is a dashboard description. This provides information about what the dashboard is reporting and what each of the filters are. The description is always collapsed by default.

The dashboard is then split into 5 main sections:

There are several filters available to filter the data to a more fine-grained level as necessary and are explained in further detail below.

Time Range

The time range for which the dashboard displays data is configurable in the top right of the dashboard using the Time Range selector (defaults to the last 3 hours):

There are a number of predefined quick ranges to choose from:

  • Last 5, 15 and 30 minutes
  • Last 1, 3, 6, 12 and 24 hours
  • Last 2, 7, 30 and 90 days
  • Last 6 months
  • Last 1, 2 and 5 years
  • Yesterday
  • Day before yesterday
  • This day last week
  • Previous week, month, fiscal quarter, year, fiscal year
  • Today
  • Today so far
  • This month, fiscal quarter, year and fiscal year
  • This month, fiscal quarter, year and fiscal year so far

To configure an absolute time range, you should specify a From and To date and time. These values can be in the format of YYYY-MM-DD HH:MM:SS, e.g. 2022-07-22 13:54:23, or alternatively can use times relative to now, e.g. now-24h. It is also possible to use the date time picker available for both the From and To fields. Once the absolute time range has been configured you must click the ‘Apply time range’ button.

If an absolute time range is specified, the Time Range selector will show the selected time range with arrows either side. These arrows can be used to shift the time range forwards and backwards. This feature is not available for quick ranges.

The magnifying glass icon allows you to zoom out of the time range specified. It will substract half the current time range from the From field and add half the current time range to the To field.

For more information regarding the Time Range selector, see Grafana’s Time range controls documentation.

Filters

At the top of the dashboard, there are 9 filters available to restrict the data queried:

Filter Description
Tenant List of tenants. Defaulted to All.
System List of systems. Defaulted to All.
Node List of hosts that processed the requests. Defaulted to All.
API List of the API endpoints found in the HTTP requests. Defaulted to All.
Status Code List of status codes found in the HTTP responses. Defaulted to All.
Result List of results found in the HTTP responses. Defaulted to All.
Initiator IP Address List of IP addresses for the initiators of the requests. Defaulted to All.
Interval List of intervals to perform the time series aggregations upon. This only affects the graphs on this dashboard.

The available values for this filter are auto, 1m, 10m, 30m, 1h, 6h, 12h, 1d, 7d, 14d, 30d.

If auto is selected, as is the default, Grafana will aggregate to a level it deems appropriate for the time range specified.
Custom Filter Enables filtering on all available values, including those not exposed by default.

All filters (excluding Interval and Custom Filter) will display their list of available options dependent on the preceding filters selected.

Overview Section

This section displays key platform health metrics for the specified time range and consists of 4 panels.

Availability

This tile displays the availability of the platform by calculating the successful requests / total requests during the specified time range. Successful requests are all requests that do not result in a 5xx HTTP response, 4xx responses are considered successful in this scenario. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be customised, however the default thresholds are:

Threshold Value Colour
OK >= 95% green
WARNING >= 90% orange
CRITICAL < 90% red

Total Requests

This tile displays the total number of requests during the specified time range.

Errored Requests

This tile displays the total number of errored requests during the specified time range. Errored requests are all requests that result in an unknown or 5xx HTTP response, 4xx responses are considered successful in this scenario. This tile has thresholds set to colour code the tile depending on the value. These thresholds can be customised, however the default thresholds are:

Threshold Value Colour
OK 0 green
CRITICAL >= 1 red

Mean Request Duration

This tile displays the mean duration for requests during the specified time range.

Availability Section

This section displays the availability of the Cortex Innovation platform and consists of 1 panel.

Availability

This graph displays the availability of the Cortex Innovation Platform during the specified time range by calculating successful requests / total requests. Successful requests are all requests that do not result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario.

Each data point value is calculated by aggregating requests based on the Interval filter. If there is no data for the previous interval, the line will be broken as the availability is not known at the time.

This graph has thresholds set to colour code the background to show when availability drops into warning and critical levels. These thresholds can be customised, however the default thresholds are:

Threshold Value Colour
OK >= 95% green
WARNING >= 90% orange
CRITICAL < 90% red

This graph is configured to start the availability axis at 80%. However, if the availability drops below this level, the axis will modify to show the lowest availability level.

Requests Section

This section provides information regarding the history of the requests processed by the Cortex Innovation platform for the specified time range and consists of 2 panels.

Requests

This graph displays, for the specified time range, the:

  • count of all requests. Each data point value is calculated by aggregating requests based on the Interval filter.
  • count of all requests per second.

Top 10 Responses by Total Count

This table displays the Top 10 HTTP responses that occurred during the specified time range with their mean, minimum and maximum duration in seconds.

Errors Section

This section provides information regarding the errored request history for the specified time range and consists of 2 panels.

Errored Requests

This graph displays, for the specified time range, the:

  • count of errored requests
  • count of all requests

Each data point value is calculated by aggregating requests based on the Interval filter.

Errored requests are all requests that result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario.

Top 10 Error Responses by Error Count

This table displays the Top 10 HTTP error responses that occured during the specified time range with their mean, minimum and maximum duration in seconds. Errored requests are all requests that result in an unknown or 5xx HTTP response. 4xx responses are considered successful in this scenario.

Duration Section

This section provides information regarding the request duration history for the specified time range and consists of 2 panels.

Request Duration

This graph displays, for the specified time range, the:

  • mean duration in seconds for all requests
  • minimum duration in seconds for all requests
  • maximum duration in seconds for all requests

Each data point value is calculated by aggregating requests based on the Interval filter.

Top 10 Responses by Mean Duration

This table displays the top 10 HTTP responses that occurred during the specified time range with their mean, minimum and maximum duration in seconds.

Remarks

Unknown values

The dashboard may display HTTP requests that have an Unknown status code or result, if they are missing from the raw logs. The chances of this occurring are minimal.

Breaks in Graph Lines

When appropriate, there may occur breaks in the line graphs. This is relevant to the Availability graph. When there is no data, it is not appropriate to say that the availability is the same as the previous data point or that it is zero as if there is no data, we cannot accurately reflect the data at this point, and therefore, the line will break.

Known Limitations

Graphs do not reset to zero

There is a limitation in Grafana where the graph does not always return to the zero line when there is no data for a given time point. This only occurs when there is a data point available at the beginning of the graph, followed by a period with no data, then data occurs again. When hovering the mouse over this area, it will show that the value is 0, and any other tiles will reflect the zero data at this point accordingly.

None

6.8.1.2 - Advanced Setup

This section includes supporting documentation for the Grafana Observability platform.

6.8.1.2.1 - Configuring Thresholds

Instructions on how to configure thresholds in the Grafana Dashboard panels.

Configuring Thresholds

Configure Thresholds

This section explains how to change the colour coding of thresholds set for the thresholded panels in the dashboards.

  1. Log in to your configured Grafana with a user that has the Admin role.
  2. To open a dashboard:
    1. Click the Dashboards icon Dashboards Icon in the side menu, and then click Browse.
    2. Click the folder name that the dashboards were imported to.
    3. Click the name of the dashboard you wish to modify to open it.
  3. Open the panel you wish to configure in edit mode:
    1. Click the title of the panel to display a drop-down menu.
    2. Click Edit.
  4. On the Edit Panel page, on the right-hand side, scroll down through the list of options until you reach the Thresholds section.
    1. You can change the value configured for the colours defined if the thresholds should be different to the default set for that panel.
    2. You can change the colours defined for the thresholds to be different to the default set for that panel.
    3. You can add additional threshold levels by clicking + add threshold and configuring the colours and numbers appropriately. E.g. on the Total Requests Errored panel on the Flow Execution Requests dashboard, you may wish to add a warning threshold level to be >= 1 errors and change the critical threshold to be >= 10. For this you should add a threshold and set the colour to your preferred colour, set the value to 1 and change the value for red to be 10.
    4. The threshold should be set to be an absolute value if it is a count e.g. error count, or a percentage if it is a rate e.g. success rate.
  5. Click Apply in the top right corner of the Edit Panel page.
  6. Save the changes to the dashboard by clicking on the save (disk) icon, in the top right of the dashboard.

6.9 - Troubleshooting

This section includes information about how to troubleshoot the platform.

6.9.1 - Installation

Information on troubleshooting Cortex Innovation installations.

Installation

Troubleshooting issues during installation

Root certificate verification failed as no root certificate has been specified

If the installation fails with Root certificate verification failed as no root certificate has been specified. it means that Windows has not got the trusted root installed for the provided X.509 certificate. This can be rectified by providing the path to a .pem file containing the root certificate in the pemRootCertificatePath property for each certificate in the serverCertificates and/or adminCertificates section of the configuration file. After adding this, the installation script can be re-run. The following steps can be taken to create a .pem file and re-run the installation (these instructions may differ slightly depending on the Certificate Authority):

  1. In order to find out the issuer of the certificate, if not already known, the following script can be used, replacing the password for the pfx file and certificate path as necessary:

    $p = ConvertTo-SecureString -String "pfxPassword" -AsPlainText -Force
    $c = Get-PfxData -Password $p -FilePath "C:\Certificates\serverCert.pfx"
    $c | Format-List
    
  2. This will give a list of Other Certificates and End Certificates contained in the .pfx file. The issuer can be found in the Issuer property of one of the Other Certificates. If there are more than one, it will be the one that does not appear as a Subject in any of the other items.

  3. E.g. For a “Let’s Encrypt” certificate this will give the following results:

    OtherCertificates     : {[Subject]
                              CN=Let's Encrypt Authority X3, O=Let's Encrypt, C=US
                            [Issuer]
                              CN=DST Root CA X3, O=Digital Signature Trust Co.
                            [Serial Number]
                              0A0141420000015385736A0B85ECA708
                            [Not Before]
                              17/03/2016 16:40:46
                            [Not After]
                              17/03/2021 16:40:46
                            [Thumbprint]
                              E6A3B45B062D509B3382282D196EFE97D5956CCB
                            }
    EndEntityCertificates : {[Subject]
                              CN=*.domain.com
                            [Issuer]
                              CN=Let's Encrypt Authority X3, O=Let's Encrypt, C=US
                            [Serial Number]
                              03D3B2E5E7D75175C25B250305650ABE849A
                            [Not Before]
                              20/12/2019 16:27:36
                            [Not After]
                              19/03/2020 16:27:36
                            [Thumbprint]
                              D61356405B8D4AA11C29AF3D20F2D834C1A3039F
                            }
    
  4. In this case, the root certificate is DST Root CA X3.

  5. In a search engine, search for the CN of the issuer and one of the results should lead to a download of a .pem file or to a page with the certificate on it, which can then be copied and saved into a file with a .pem extension. Often, searching the issuer of the EndEntityCertificate, in the above case Let’s Encrypt, will also work.

  6. E.g. for Let’s Encrypt, the results of the search for DST Root CA X3 leads to https://www.identrust.com/dst-root-ca-x3 which provides the following text to be saved as a .pem file:

    -----BEGIN CERTIFICATE-----
    MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/
    MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
    DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow
    PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD
    Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
    AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O
    rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq
    OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b
    xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw
    7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD
    aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
    HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG
    SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69
    ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr
    AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz
    R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5
    JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo
    Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
    -----END CERTIFICATE-----
    
  7. After saving the .pem file, transfer it to the same directory as other installation certificates.

  8. Modify the installation configuration file to include the .pem file as the pemRootCertificatePath in the serverCertificates like so:

      "serverCertificates"{
        "serverCert": {
          "pfxCertificatePath": "C:\\Certificates\\wildCardCert.pfx",
          "pfxCertificatePassword": "pfxPassword",
          "pemRootCertificatePath": "C:\\Certificates\\rootCert.pem"
        }
      }
    
  9. If a load balancer is being used (not single server), modify the installation configuration file to include the .pem file as the pemRootCertificatePath in the adminCertificates like so:

      "adminCertificates"{
        "loadBalancerCert": {
          "pfxCertificatePath": "C:\\Certificates\\lbCert.pfx",
          "pfxCertificatePassword": "pfxPassword",
          "pemRootCertificatePath": "C:\\Certificates\\lbRootCert.pem"
        }
      }
    
  10. Run the installation script again.

RabbitMQ commands not succeeding

When running the installation, if you get errors similar to the following:

Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames  .  Attempt 1
Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames  .  Attempt 2
Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames  .  Attempt ...
Retry rabbitmqctl start_app --erlang-cookie $ErlangCookie --longnames  .  Attempt 20

It means there is probably something wrong with the certificate verification with RabbitMQ. Please report issues like this to Cortex Service Portal.

To work around this error, either uninstall the platform and reinstall it using a different certificate, otherwise disable peer-to-peer verification in RabbitMQ by carrying out the following steps:

  1. Uninstall the platform by taking the following steps:

    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Uninstall the platform by running the following command for your architecture:

    
            .\Cortex.Innovation.Uninstall.ps1
            
    
            .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer
            
    1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.
    2. Wait for the command to finish.
  2. In the Cortex Innovation 2022.9 - App Server Install Scripts folder, navigate to Resources.

  3. Backup the file RabbitMqInterNodePublicTemplate.config and then open it with a text editor.

  4. Replace both instances of the text verify_peer with the text verify_none.

  5. Change the value of both occurrences of fail_if_no_peer_cert to false so that they resemble the following:

    {fail_if_no_peer_cert, false},
    
  6. Save and close RabbitMqInterNodePublicTemplate.config.

  7. Re-run the installation script.

Troubleshooting issues after installation

Cortex Innovation features not visible in Cortex Gateway

Check that the Feature Flags Guid in the CortexGateway.SetParameters.xml file used for installing Cortex Gateway is correct. If it is not, update it and reinstall Cortex Gateway or update the value in the web.config file and restart the website. If the value is correct, please contact Cortex Service Portal for assistance.

Cortex Innovation blocks not visible in Cortex Studio

Check that the Dot NET flow debugger Endpoint URL in the CortexGateway.SetParameters.xml file used for installing Cortex Gateway is correct pay particular attention to the protocol - it should usually be https. If it is not, update it and reinstall Cortex Gateway or update the value in the web.config file and restart the website.

Ensure that the Flow Debugger Service is running. Open IIS, click on Application Poolsand ensure there is a debugger application pool which is showing that it is associated with 1 application. If not, go back to the Cortex Flow Debugger Service installation steps and ensure that all steps were followed correctly.

If no misconfiguration can be found, the service log files may contain more information. These can be found on the Web Application Server at:

  • %ProgramData%\Cortex\Cortex Flow Debugger
  • C:\temp\Cortex.Gateway.log

Restart the Cortex website. Open IIS, In the Connection pane, browse to Sites. Select the Cortex website and click Restart in the Manage Website pane.

If the issues cannot be resolved, please contact Cortex Service Portal for assistance.

Cannot publish a package

Check that the Service Fabric Api Gateway Endpoint, Service Fabric Using Self Signed Certificates, Service Fabric ApiGateway Basic Auth Username and Service Fabric ApiGateway Basic Auth Password in the CortexGateway.SetParameters.xml file used for installing Cortex Gateway are correct. If any of them are not, update them and reinstall Cortex Gateway or update the value in the “web.config” file and restart the website. If the value is correct, please contact Cortex Service Portal for assistance.

Ensure that the Application Services are healthy by following these steps:

  1. Log on to one of the Application Servers and open a web browser.

  2. Navigate to https://app-server.domain.com:9080/Explorer, where app-server.domain.com is the fully qualified domain name of any Application Server. Replace 9080 with new httpGatewayEndpointPort value if it was changed during configuration.

    If page access is denied it may be necessary to import the server certificate used in installation to the Current User certificate store (usually achieved by double clicking on it and following the wizard). If using self-signed certificates, the certificate can be retrieved by using the Manage Computer Certificates tool in Windows to export the CortexServerCertificate from the Personal store and then importing it to the Current User store by double-clicking on it and following the wizard. The browser may need to be restarted before the site can be accessed

    The screen should resemble that in the following figure, all services should have Health State = OK and Status = Active. All instances below the service should have Health State = OK and Status = Ready.

    Healthy Service Fabric Explorer

    If any warning triangles appear, wait for 5 minutes or so as the cluster may still be starting up. If the cluster looks OK, ignore the rest of this step. If the warnings persist or anything on the screen goes red, use the filter buttons to find the individual elements which have errors or warnings. Warnings should not be ignored as they can indicate that the service can’t start but is still in the retry phase. If no useful message can be seen here, the service log files may contain more information.

If no solution can be found, please contact Cortex Service Portal for assistance.

Managing RabbitMQ

There may be times when the logs provided by the Cortex Services and the errors displayed in Service Fabric Explorer are not enough to debug an issue that is occurring on the system. This can be due to RabbitMQ being a state where it can’t send messages between services.

To check that RabbitMQ is working as expected, remote desktop to an Application Server and navigate to https://app-server1.domain.com:15671, replacing app-server1.domain.com with the FQDN of one of the Application Servers. Sign in with username ‘administrator’ and the RabbitMQ password provided during the Application Server installation. The following should be displayed in the overview tab for a healthy cluster:

Healthy RabbitMQ status.

If there are any unhealthy nodes (red) you may need to restart the RabbitMQ Windows service on each of the nodes that is erroring. These can be restarted in any order, but they must be restarted one at a time; wait for the node in the RabbitMQ explorer to be green before restarting the next one (you may need to refresh the browser).

Service Fabric Explorer displays errored services with RabbitMQ Broker Unreachable Exceptions

If, when checking Service Fabric Explorer, all services are showing as erroring and the details are displaying a message similar to the following:

RabbitMQ.Client.Exceptions.BrokerUnreachableException (-2146232800)
None of the specified endpoints were reachable

There may be due to an incompatibility between the version of OpenSSL used and your processor. From Intel’s website: “OpenSSL 1.0.2 beta (Jun 2014) to OpenSSL 1.0.2k (Jan 2017) contain bugs that either cause a crash or bad SHA (Secure Hash Algorithm) values on processors with the SHA extensions. Both bugs were fixed years ago; however, any application that uses the old version directly, or as one of its dependencies, will fail”*

To verify that this is the problem, open Event Viewer and look in Windows -> Application. If this problem has occurred there will be some errors in the event viewer which contain the following:

Faulting application name: erl.exe, version: 0.0.0.0, time stamp: 0x5d80b978
Faulting module name: crypto.dll, version: 0.0.0.0, time stamp: 0x5d80baab

A workaround for this is provided by Intel.

  1. Uninstall the platform by taking the following steps:

    1. Open a Windows PowerShell (x64) window as administrator.

    2. Navigate PowerShell to inside the Cortex Innovation 2022.9 - App Server Install Scripts folder using the following command, modifying the path as necessary:

      cd "C:\Install\Cortex Innovation 2022.9 - App Server Install Scripts"
      
    3. Uninstall the platform by running the following command for your architecture:

    
            .\Cortex.Innovation.Uninstall.ps1
            
    
            .\Cortex.Innovation.Uninstall.ps1 -SkipLoadBalancer
            
    1. A credentials prompt will appear. Enter credentials of a domain user that is a member of the local Administrators group on all servers (Application and Load Balancer) and press OK.
    2. Wait for the command to finish.
  2. Add a system environment variable, provided by Intel, to each Application Server by taking the following steps:

    1. Remote desktop to one of the Application Servers.
    2. Right-click on the Start Menu and select System.
    3. Click Advanced system settings to open the System Properties dialog.
    4. Click Environment Variables....
    5. Under System variables, click New... to open the New System Variable dialog.
    6. Set the Variable name to OPENSSL_ia32cap and the Variable value to :~0x20000000. Make sure to include the colon at the start.
    7. Click OK.
    8. Repeat these steps for any other Application Servers.
  3. Run the Application Servers installation script again.

Service Fabric Explorer displays certificate is about to expire warning

If Service Fabric certificates are going to expire in fewer than 30 days, a warning is displayed as follows:

Service Fabric Explorer Certificate Expiring

Certificate expiration: thumbprint = {thumbprint}, expiration {date} remaining lifetime is {time} please refresh ahead of time to avoid catastrophic failure.

If this occurs on your server it is important to update your certificates as soon as possible using Rollover Certificates.

6.10 - Glossary

Explanation of terms, words and phrases used throughout the Cortex documentation.

6.10.1 - A-E

Terms, words and phrases beginning with the letters A through E.

A-E

Terms, words and phrases beginning with the letters A through E.

A

Acceleration Program

See Acceleration Program.

API

An API (Application Programming Interface) is a set of functions that allows applications to access data from and interact with external systems, services or applications.

Autogeneration

Autogeneration, is the process in which something is created automatically for use within a process.

Automate

The application of automation.

Automation

Automation is a term for techniques, methods, systems or technologies that reduce human intervention in tasks and processes.

AWS Lambda

AWS Lambda is an event driven serverless solution from AWS. Instead of deploying and maintaining servers, cloud infrastructure is used to run applications.

Azure Functions

Azure Functions is an event driven serverless solution from Microsoft. Instead of deploying and maintaining servers, cloud infrastructure is used to run applications.

B

BCC

Blind Carbon Copy (BCC) is a way of sending copies of an email to other people. Unlike CC recipients, the other recipients of the email will not be able to see who recieved the email via BCC.

Bit

A bit is the most basic unit of information in computing, and represents a logical state with one of two possible values; most commonly represented as 1 or 0.

See Wikipedia for more information.

Block

Blocks (or functional blocks) expose the logic and actions that the Cortex platform is able to execute for the flow developers; alongside flows they are one of the main components used to define how to automate tasks and processes.

For more detailed information about blocks, see Fundamentals > Blocks.

For a complete list of available blocks, see Reference > Blocks.

Block Property

Blocks have block properties (or properties) that allow the flow developers to configure how the block should behave; e.g. a block to send emails would have properties for specifying things like the sender, recipients, summary, body, attachments etc.

For more detailed information about configuring blocks using block properties, see Fundamentals > Block Properties.

Boolean

A data type that represents a logical value of true or false.

For more detailed information about the Boolean data type, see Data Types > Boolean.

Byte

A byte is a unit of information in computing that most commonly consists of eight bits.

See Wikipedia for more information.

C

C#

C# (pronounced “see sharp”) is a programming language developed by Microsoft.

It is natively supported by the Cortex platform for using simple expressions (i.e. 1 + 1) and more complex code (i.e. DateTime.Now.AddDays(1)) within flows.

C# expressions and code can be entered as the values for Fundamentals > Block Properties using the Expression Editor.

See the official C# documentation for more information about C#.

camelCase

camelCase is a typographical convention in which phrases are written without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word starting with a lowercase letter. E.g. “iPhone” and “eBay”.

camelCase is often used as a naming convention in programming languages such as C#.

See also PascalCase.

Case-insensitive

If something is case-insensitive, it means it ignores differences in case (i.e. CASE is considered equal to case).

Case-sensitive

If something is case-sensitive, it means it considers differences in case (i.e. CASE is considered not equal to case).

Cast

The process of explicitly converting one data type to another.

See Casting and type conversions (C# Programming Guide) for a detailed technical explanation of casting in C#, the programming language natively supported by the Cortex platform for writing simple expressions and more complex code.

Also see Explicit Cast for more information.

CC

Carbon Copy (CC) is a way of sending copies of an email to other people. The other recipients of the email will be able to see who recieved the email via CC.

CI/CD

CI/CD is a software development practice and is broken down into the following concepts:

Char

A data type that represents a character or letter.

For more detailed information about the Char data type, see Data Types > Char.

Cloud

A global network of servers which are linked together and operate as a single ecosystem.

Examples of publicly available Cloud providers include:

  • Amazon AWS
  • Google Cloud Platform
  • Microsoft Azure

Cloud Service Provider

A cloud service provider is a third-party company offering a cloud-based platform, infrastructure, application, or storage services.

Code

A set of instructions in a computer program.

Concurrent

At the same time.

Continuous Integration

Continuous Integration is a software development practice where developers frequently:

  • Integrate their local changes with source code from the main branch
  • Use automated testing to ensure that their changes work as expected
  • Merge their changes into the main branch, if no issues were found

Continuous Delivery

Continuous Delivery is a software development practice where:

  • Changes to the main branch are detected
  • The main branch is packaged into deployment artefacts
  • Deployment artefacts are made available

Continuous Deployment

Continuous Deployment is a software development practice which extends Continuous Delivery by automatically deploying the generated artefacts.

Convert

To change something into a different form. E.g. Change some text from lowercase to UPPERCASE.

Cortex

The name of the new and current generation of the Cortex automation platform.

Cortex Gateway

The centralised web-based portal for accessing all user applications and tooling in the Cortex platform.

Cortex Studio

The web-based integrated development environment (IDE) for creating, editing, debugging, testing and managing flows that define the logic and actions required to capture and automate a task or process.

For more detailed information about Cortex Studio, see Guides > Cortex Studio.

Culture

Describes a set of rules for data that differs between different cultures; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and text comparisons.

For more detailed information about Culture, see Working With > Culture.

Culture identifier

A culture identifier is a standard international numeric abbreviation and has the components necessary to uniquely identify one of the operating system’s installed cultures.

For more detailed information about Culture, see Working With > Culture.

Culture-insensitive

If something is culture-insensitive, it means that it does not get affected by culture related changes to the operating system, such as language and regional settings.

Culture-sensitive

If something is culture-sensitive, it means that it does get affected by culture related changes to the operating system, such as language and regional settings.

Current Culture

The current culture used by the executing thread; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons.

For more detailed information about Culture, see Working With > Current Culture.

CRL

Certificate Revocation List (CRL) is a list of certificates that have been revoked by the issuing certificate authority prior to their actual/assigned expiration date. It is essentially a list of certificates that should no longer be trusted.

D

Data Type

A data type (or type) defines the type of data or values that a block property can accept.

For more detailed information about data types, see Fundamentals > Data Types.

For a complete list of available data types, see Reference > Data Types.

Debug

The ability for flow developers to execute and interact with a flow step-by-step from within Cortex Studio, so that they are able to identify and remove errors in the flow’s logic and actions.

For more detailed information about debugging in Cortex Studio, see Cortex Studio > Debugging.

Default Value

The default that is assigned as the value of a block property when a new block is added to a flow.

Design Sprint

See Design Sprint

Developer

A developer is an individual that builds and creates software and applications.

Dictionary

A data type that represents an unordered collection of key-item pairs, where each pair consists of a unique key and its associated item. Dictionaries are optimised for fast lookup of items using their key.

For more detailed information about the Dictionary data type, see Data Types > Dictionary<TKey, TItem>.

DLL

DLL files are binary files that can contain executable code and resources.

Drag-and-Drop

Functionality that allows a user to select an object and move it to another location.

Double

A data type that represents a fractional, or very large or small number from -1.79769313486232e+308 through 1.79769313486232e+308.

For more detailed information about the Double data type, see Data Types > Double.

dynamic

A data type that indicates that any data type can be used.

For more detailed information about the dynamic data type, see Data Types > dynamic.

E

Empty

Empty indicates that a data type has been initialised and has a non-null value, but the value does not contain any data. E.g. a string that contains no characters "", or a list that contains no items [].

Empty is not the same as null.

Error

Something which is inaccurate or incorrect; a mistake.

Example

An example is intended to show flow developers how something works. Examples can be found near the top of every block’s help page. See examples for the Add Text At Beginning block.

Exception

An exception represents errors that occur during the execution of a flow.

Exceptions are data types that can be reasoned with during the execution of a flow, in order to handle errors during the automation of a task or process.

For more detailed information about exceptions, see Fundamentals > Exceptions.

For a complete list of available blocks that can be used to handle exceptions, see Blocks > Exception Blocks.

For a complete list of exceptions, see Reference > Exceptions.

Execution

When a request to start a flow is received by the Cortex platform, an execution is created that represents that instance of the executing flow.

There can be multiple executions of a flow running concurrently.

For more detailed information about executions, see Cortex Studio > Debugging.

Explicit Cast

Sometimes, in order to convert one data type to another, an “explicit cast” expression is required; this is typically needed when information might be lost in the conversion, or when the conversion might not succeed for other reasons.

An example would be converting a 32-bit integer (Int32) to a 16-bit integer (Int16):

Int32 ThirtyTwoBitInteger = 100;
Int16 SixteenBitInteger = (Int16)ThirtyTwoBitInteger;

See Cast expression (C# Reference) for a detailed technical explanation.

Also see Cast for more information.

Expression

An expression is a combination of operands (i.e. variables, literals, calls to methods and properties exposed on data types) and operators (i.e. =, +, -, *, /) that can be evaluated by the Cortex platform to a single value.

Expressions use the syntax of the C# programming language.

For more detailed information about expressions, see Fundamentals > Expressions.

Expression Editor

The Expression Editor is a web-based text editor that allows flow developers to use either simple expression or more complex code as the value of a block property.

It is based on the Monaco Editor used by VS Code, and includes a rich set of features including:

For more detailed information about the Expression Editor, see Cortex Studio > Expression Editor.

6.10.2 - F-J

Terms, words and phrases beginning with the letters F through J.

F-J

Terms, words and phrases beginning with the letters F through J.

F

File

A file is an object on a computer that stores data.

Different files can store different types of data (i.e. a text file, .txt, stores textual data; an executable file, .exe stores data required for executing an application).

Flow

A flow is an object in Cortex Studio that contains the logic and actions (in the form of blocks) that the Cortex platform is able to execute for the flow developers.

For more detailed information about flows, see Fundamentals > Flows.

Flow Developer

A flow developer is a user that has been granted permissions to develop flows in Cortex Studio.

For more detailed information about granting permissions to develop flows, see Cortex Studio > Authorisation.

Folder

A folder (or directory) is an object on a computer that contains files.

Folders can contain different types of file and can also contain other folders.

Format Parameter

See Text > Format Parameters.

Format Specifier

See Text > Format Specifiers.

Format Template

See Text > Format Templates.

Functional Block

See block.

G

Generics

Generic means not specific to a particular data type.

An example of a generic data type is List<TItem> where TItem is a placeholder which indicates it can be initialised with any data type, such as:

  • List<int> and List<string> which are homogenous lists that can only contain integers and strings respectively
  • List<object> and List<dynamic> are heterogenous lists that can contain multiple data types

Gmail

Gmail is a free web-based email service provided by Google.

GUI

GUI stands for “Graphical User Interface”. It is used to graphically display information and represent user interactions with a system, without the need for typing commands.

H

Heterogenous

Consists of dissimilar or diverse constituents.

Heterogenous collections can contain multiple data types (e.g. List<dynamic>).

Collections that can only contain a single data type are known as homogenous.

Homogenous

Consists of the same or a similar constituents.

Homogenous collections can only contain a single data type (e.g. List<int>).

Collections that can contain multiple data types are known as heterogenous.

I

IDE

IDE or Integrated Development Environment is a software application such as Cortex Studio, that allows users to create a program or application.

In Cortex Studio, the users are called flow developers, and the programs are called flows.

Some common and popular examples of IDE’s include:

  • Visual Studio
  • VSCode
  • Eclipse

IMAP

Internet Messaging Access Protocol (IMAP) in an internet protocol used by email clients to retrieve email messages from a mail server.

Immutable

Unable to be changed.

Implicit Cast

The process of an application converting one data type to another, without requiring an explicit instruction from the developer.

For one data type to be able to be implicitly cast to another, there should be no data loss during the conversion.

An example would be converting a 16-Bit integer (Int16) to a 32-Bit integer (Int32), as the entire range of the 16-bit integer will fit into a 32-bit integer:

Int16 SixteenBitInteger = 100;
Int32 ThirtyTwoBitInteger = SixteenBitInteger;

See Explicit Cast for an example of where data loss would occur during conversion, and would therefore require an explicit instruction from the developer.

See Casting and type conversions (C# Programming Guide) for a detailed technical explanation of casting in C#, the programming language natively supported by the Cortex platform for writing simple expressions and more complex code.

Index

An Index is used to access an item in a list and relates to the position of the item in the list.

Indexes are 0 based (e.g. The first item in a list is at index 0, the second item is at index 1, etc.).

See Collections > Indexes.

Intellisense

IntelliSense is a general term for various code editing features such as code completion and snippets.

Initialised

A variable is initialised when its value has been set for the first time.

Input

Input properties are used to provide values to a block. These properties are used in the block’s execution.

See Block Properties > Input Properties.

InputOutput

InputOutput properties are used to provide values to a block. These properties are used, updated and saved back to a variable during the block’s execution.

See Block Properties > InputOutput Properties.

Integer

A whole number (e.g. 100).

Int16

A data type that represents a whole number from -32,768 through 32,767.

For more detailed information about the Int16 data type, see Int16.

Int32

A data type that represents a whole number from -2,147,483,648 through 2,147,483,647.

For more detailed information about the Int32 data type, see Int32.

Int64

A data type that represents a whole number from -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807.

For more detailed information about the Int64 data type, see Int64.

Invariant Culture

A culture associated with the English language, but not with any country or region; it determines the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons.

It has a stable and unchanging set of rules that cannot be customized and is unaffected by culture related changes to the operating system.

See Working With > Invariant Culture.

Item

Each object within a collection is called an item.

IT

IT stands for Information Technology, which is the use of computers to create, process, store, retrieve, and exchange electronic data and information.

See Wikipedia for more information.

J

JSON

JSON stands for JavaScript Object Notation, and is a format for storing and transporting data between computer applications.

See What is JSON for more information.

6.10.3 - K-O

Terms, words and phrases beginning with the letters K through O.

K-O

Terms, words and phrases beginning with the letters K through O.

K

Kickstarter

Free two/three day workshop that enables the rapid configuration of a cloud-based Cortex platform to prototype, and demonstrate automation in context.

See Kickstarter.

L

Launch Program

A twelve week program which takes your team through the phases of mobilisation, design of automation, trial testing and sign-off to production.

See Launch Program.

Linux

Linux is an open-source Unix-like operating system based on the Linux kernel.

List

A data type that represents a list of items that can iterated or looped over.

For more detailed information about the List data type, see Data Types > List<TItem>.

Literal

A literal is an explicit value that is not calculated during the execution of the flow. A literal can be any of the following data types:

lowercase

The term lowercase refers to small letters (a,b,c …) as distinguished from capital letters (A,B,C…).

Low-code

Low-code is an approach to developing automation through a graphical user interface (GUI) that requires little to no coding; where the developers predominantly use drag-and-drop features, rather than writing code.

M

Method

In C#, a Method is used to execute behaviour of a data type (e.g. the ToString() method returns a text representation of the data type).

See Method Expressions for information on how methods can be used within the expression editor.

N

Non-Null

Non-Null indicates that a data type has been initialised and has a value.

Nuget Package

A NuGet package is a ZIP file with the .nupkg extension. It contains compiled code (DLLs), other files related to that code.

NuGet can be published and shared to a public or private host.

Null

Null indicates that a data type has been initialised with no value.

O

Object

A data type that indicates that any data type can be used.

For more detailed information about the Object data type, see Data Types > Object.

Occurrence

A value can occur in a collection multiple times, these are called Occurrences.

Occurrences are 1 based (e.g. The first occurrence of an item in a list is at occurrence 1, the second occurrence of an item is at occurrence 2, etc.).

See Collections > Occurrences.

On-premise

On-premise refers to infrastructure and software that is deployed and running within a physical location of an organisation.

Operand

Describes a literal or variable that has the capability to be operated on. For example, in the expression 1 + 2 the literal values 1 and 2 are operands, whereas + is an operator.

Operator

Operators are used to manipulate and check operands values. For example, in the expression 1 + 2 the operator + adds the two operands 1 and 2, resulting in the expression evaluating to 3.

For more detailed information about operators, see C# operators and expressions.

Output

Output properties are used to save values from a block. These properties will saved to a variable during the block’s execution.

See Block Properties > Output Properties.

Out-of-the-box (OOTB)

Out-of-the-box functionality of a product that works immediately after any installation without any configuration or modification.

Outlook

Outlook is a free web-based email service provided by Microsoft.

6.10.4 - P-T

Terms, words and phrases beginning with the letters P through T.

P-T

Terms, words and phrases beginning with the letters P through T.

P

PascalCase

PascalCase is a typographical convention in which phrases are written without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word also starting with a capitalized letter. E.g. “FirstName” and “LastName”.

PascalCase is often used as a naming convention in programming languages such as C#.

See also camelCase.

Platform

The environment in which software is executed. This can include the hardware, operating system, web browsers or other programs.

Portal

A portal is a specially designed website that serves as a single point of access for information or functionality.

PowerShell

See Windows PowerShell

PowerShell Core

An open-source version of PowerShell that can be run on various platforms, such as:

  • Linux
  • macOs
  • Windows

See What is PowerShell? for more information about PowerShell Core and Windows PowerShell.

Process

A process is a collection of related, structured tasks completed by people or equipment in a specific sequence.

Programming Language

A programming language is a notation for writing computer programs, which are specifications of a computation or algorithm.

Property

Block (property)

See Block Property.

C# (property)

In C#, a Property is used to access or update attributes of a data type (e.g. the Message property of an Exception returns the reason the exception occurred).

See Property Expressions for information on how properties can be used within the expression editor.

Property Type

There are three types of block property:

See Block Properties > What is a Block Property.

Q

R

Read-only

Refers to computer files or memory that can be read or used, but not updated or added to in any way.

Request

A method of communication over a network, in which one computer sends a request to another, which can then respond to the request.

S

SASL

Simple Authentication and Security Layer (SASL) is a framework for protocols like SMTP and IMAP to add authentication support.

SDK

SDK stands for “Software Development Kit”, and is a collection of software development tools.

An SDK facilitates the creation of applications by having a compiler, debugger and sometimes a software framework.

Service Fabric

Service Fabric is an open source project developed by Microsoft used to deliver highly available and durable services at cloud-scale.

For more information see What is Service Fabric?

Single

A data type that represents a fractional, or very large or small number from -3.402823e+38 through 3.402823e+38.

For more detailed information about the Single data type, see Data Types > Single.

SMTP

Simple Mail Transfer Protocol (SMTP) is an internet protocol for email transmission. Mail servers typically only use SMTP to send emails.

Snippets

Snippet is a term for a small section of re-usable code.

Snippets can be accessed from any editor using Intellisense.

Software Development

The process of developing software.

SSL

Secure Sockets Layer (SSL) is the technology that keeps an internet connection secure via the encryption of data in transit.

String

A data type that represents text.

For more detailed information about the String data type, see Data Types > String.

Structure

A data type that represents a collection of key/item pairs, where each pair consists of a unique String key and its associated item.

For more detailed information about the Structure data type, see Data Types > Structure.

Syntax Highlighting

Syntax highlighting is a feature of text editors that are used for programming. The feature displays text in different colours and fonts according to a category of terms.

Syntax Highlighting improves the readability and provides context of text, and can be used to identify errors within a block of code.

T

Task

A unit of work to be done or undertaken.

Text

Data which can be interpreted as human-readable text, this is represented by Strings in C#.

Title Case

Title Case is a typographical convention in which the first letter of all words are capitalized and all other letters lower cased; except for words that are entirely upper cased, such as acronyms, which remain upper cased.

TLS

Transport Layer Security is a more secure, updated version of SSL. Note that TLS is still often referred to as SSL.

Trigger

A mechanism used to initiate an action when a specific event occurs (e.g. When a given date or time is reached).

Type

See Data Type.

Typeahead

Typeahead is a language prediction tool that is used to provide suggestions based on what a user has already typed.

6.10.5 - U-Z

Terms, words and phrases beginning with the letters U through Z.

U-Z

Terms, words and phrases beginning with the letters U through Z.

U

Unicode

Unicode is a standard used to ensure consistent encoding, representation, and handling of text.

See What is Unicode?.

UPPERCASE

The term uppercase refers to capital letters (A,B,C…) as distinguished from small letters (a,b,c …).

V

Variable

A variable is a named container for storing data that can then be used in Block Properties.

Data in a variable can be read, updated, or removed by different blocks.

For more detailed information about variables, see Fundamentals > Variables.

W

Whitespace

In programming, whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character does not correspond to a visible character, but typically does occupy an area on a page.

See Text > Empty Text and Whitespace.

Windows PowerShell

PowerShell is a task automation and configuration management program from Microsoft, consisting of a command-line shell and the associated scripting language.

See What is PowerShell? for more information about PowerShell Core and Windows PowerShell.

X

Y

Z

Zero Based

Zero Based is a way of numbering in which the initial item of a list is assigned the index 0.

6.10.6 - 0-9

Terms, words and phrases beginning with the numbers 0 through 9.

0-9

Terms, words and phrases beginning with the numbers 0 through 9.

0

0 Based

See Zero Based.

1

16-bit

16-bit refers to a measurement of units of memory or data that are 16 bits in size.

2

3

32-bit

32-bit refers to a measurement of units of memory or data that are 32 bits in size.

3rd-Party Systems

3rd-party systems refer to systems, services or applications that are not developed by Cortex.

4

5

6

64-bit

64-bit refers to a measurement of units of memory or data that are 64 bits in size.

7

8

9

7 - FAQs

Answers to our most frequently asked questions.